auditea 0.1.0.beta.1

data/lib/auditea/instrumentation/active_job.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Instrumentation
+    # Safe ActiveJob final-failure observation. Never captures job arguments.
+    module ActiveJob
+      module_function
+
+      def install!
+        return unless defined?(::ActiveJob::Base)
+        return unless defined?(::ActiveSupport::Notifications)
+        return if @installed
+
+        @installed = true
+        @reported = {}
+        @mutex = Mutex.new
+
+        ::ActiveSupport::Notifications.subscribe("retry_stopped.active_job") do |*args|
+          handle_notification(args)
+        end
+        ::ActiveSupport::Notifications.subscribe("discard.active_job") do |*args|
+          handle_notification(args)
+        end
+
+        ::ActiveJob::Base.around_perform do |job, block|
+          block.call
+        rescue StandardError => error
+          Auditea::Instrumentation::ActiveJob.report_unhandled(job, error)
+          raise
+        end
+      end
+
+      def handle_notification(args)
+        return unless Auditea.configuration.capture_active_job
+
+        event = Auditea::Instrumentation::ActiveJob.notification_event(args)
+        payload = event.payload || {}
+        job = payload[:job]
+        error = payload[:error] || payload[:exception_object]
+        error ||= Auditea::Instrumentation::ActiveJob.build_from_array(payload[:exception])
+        Auditea::Instrumentation::ActiveJob.report(job, error, duration_ms: event.duration)
+      rescue StandardError => error
+        Auditea.handle_error(error)
+      end
+
+      def report_unhandled(job, error)
+        return unless Auditea.configuration.capture_active_job
+        return if handled_by_active_job?(job, error)
+
+        report(job, error)
+      end
+
+      def report(job, error, duration_ms: nil)
+        return unless job && error
+
+        key = report_key(job, error)
+        return unless claim!(key)
+
+        evidence = {
+          "job" => {
+            "class" => job.class.name,
+            "queue" => (job.queue_name if job.respond_to?(:queue_name))
+          }.compact,
+          "exception" => {
+            "type" => error.class.name,
+            "message" => Sanitizer.truncate_string(error.message.to_s, 500)
+          }
+        }
+        evidence["job"]["duration_ms"] = duration_ms.round if duration_ms
+
+        Auditea.capture(
+          "job.failed",
+          category: "error",
+          severity: "error",
+          evidence: evidence,
+          metadata: { "sdk_event_kind" => "auto_observed" }
+        )
+      rescue StandardError => error
+        Auditea.handle_error(error)
+      end
+
+      # retry_on/discard_on are implemented through ActiveSupport::Rescuable.
+      # Ask Rescuable whether a handler exists rather than comparing the raw
+      # rescue_handlers keys: those keys are commonly stored as class-name
+      # strings, so `key === error` would incorrectly miss handled exceptions
+      # and emit job.failed before retries are exhausted.
+      def handled_by_active_job?(job, error)
+        return false unless job.class.respond_to?(:handler_for_rescue)
+
+        !job.class.handler_for_rescue(error).nil?
+      rescue StandardError
+        false
+      end
+
+      def report_key(job, error)
+        jid = job.respond_to?(:job_id) ? job.job_id : job.object_id
+        "#{jid}:#{error.class.name}"
+      end
+
+      def claim!(key)
+        @mutex.synchronize do
+          return false if @reported[key]
+
+          @reported[key] = true
+          # Bound memory of dedupe map.
+          @reported.shift if @reported.size > 1_000
+          true
+        end
+      end
+
+      def notification_event(args)
+        if args.first.is_a?(::ActiveSupport::Notifications::Event)
+          args.first
+        else
+          ::ActiveSupport::Notifications::Event.new(*args)
+        end
+      end
+
+      def build_from_array(pair)
+        return nil unless pair.is_a?(Array) && pair.size >= 2
+
+        klass = begin
+          Object.const_get(pair[0])
+        rescue StandardError
+          StandardError
+        end
+        klass.new(pair[1].to_s)
+      end
+
+      def reset_for_tests!
+        @reported = {}
+        @mutex = Mutex.new
+      end
+    end
+  end
+end

data/lib/auditea/instrumentation/exception.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Instrumentation
+    module Exception
+      module_function
+
+      def capture_from_notification(event)
+        payload = event.payload || {}
+        exception = payload[:exception_object]
+        exception ||= build_from_array(payload[:exception])
+        return unless exception
+
+        frames = safe_frames(exception)
+        path = payload[:path].to_s.split("?", 2).first
+
+        Auditea.capture(
+          "exception.raised",
+          category: "error",
+          severity: "error",
+          evidence: {
+            "exception" => {
+              "type" => exception.class.name,
+              "message" => Sanitizer.truncate_string(exception.message.to_s, 500),
+              "frames" => frames
+            }.compact,
+            "http" => {
+              "method" => payload[:method],
+              "path" => path,
+              "status" => payload[:status]
+            }.compact,
+            "rails" => {
+              "controller" => payload[:controller],
+              "action" => payload[:action]
+            }.compact
+          },
+          metadata: {
+            "sdk_event_kind" => "auto_observed"
+          }
+        )
+      rescue StandardError => error
+        Auditea.handle_error(error)
+      end
+
+      def build_from_array(pair)
+        return nil unless pair.is_a?(Array) && pair.size >= 2
+
+        klass = begin
+          Object.const_get(pair[0])
+        rescue StandardError
+          StandardError
+        end
+        klass.new(pair[1].to_s)
+      end
+
+      def safe_frames(exception)
+        return [] unless exception.respond_to?(:backtrace) && exception.backtrace
+
+        exception.backtrace.first(20).map do |line|
+          file, linenum, method_name = parse_frame(line)
+          { "file" => file, "line" => linenum, "method" => method_name }.compact
+        end
+      end
+
+      def parse_frame(line)
+        # typical: path:123:in `method'
+        if (match = line.match(/\A(.+):(\d+):in [`'](.+)[`']\z/))
+          [match[1], match[2].to_i, match[3]]
+        else
+          [line, nil, nil]
+        end
+      end
+    end
+  end
+end

data/lib/auditea/instrumentation/logger_adapter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Instrumentation
+    # Opt-in boundary for future Rails/Ruby Logger forwarding.
+    # NOT installed by default in 0.1.0.beta.1 — prevents volume, secrets, recursion.
+    #
+    # Future usage (not auto-wired):
+    #   Auditea::Instrumentation::LoggerAdapter.install!(logger)
+    class LoggerAdapter
+      def self.install!(_logger = nil)
+        raise NotImplementedError,
+              "Automatic Rails.logger forwarding is intentionally disabled in 0.1.0.beta.1. " \
+              "Use Auditea.log(level, message, ...) for structured logs. " \
+              "An opt-in adapter can be added later without transport redesign."
+      end
+
+      # Adapter surface reserved for future Logger#add forwarding into Auditea.log.
+      def initialize(logger)
+        @logger = logger
+      end
+
+      def add(_severity, _message = nil, _progname = nil)
+        raise NotImplementedError, "LoggerAdapter forwarding not enabled in beta.1"
+      end
+    end
+  end
+end

data/lib/auditea/instrumentation/request.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Instrumentation
+    module Request
+      module_function
+
+      def install!
+        return unless defined?(ActiveSupport::Notifications)
+        return if @installed
+
+        @installed = true
+        ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+          event = args.first.is_a?(ActiveSupport::Notifications::Event) ? args.first : ActiveSupport::Notifications::Event.new(*args)
+          capture(event) if Auditea.configuration.capture_requests
+          Exception.capture_from_notification(event) if Auditea.configuration.capture_exceptions
+        end
+      end
+
+      def capture(event)
+        payload = event.payload || {}
+        path = payload[:path].to_s.split("?", 2).first
+        evidence = {
+          "http" => {
+            "method" => payload[:method] || request_method(payload),
+            "path" => path,
+            "status" => payload[:status],
+            "duration_ms" => event.duration&.round
+          }.compact,
+          "rails" => {
+            "controller" => payload[:controller],
+            "action" => payload[:action],
+            "format" => payload[:format]&.to_s
+          }.compact
+        }
+
+        if payload[:params] && Auditea.configuration.capture_request_params
+          evidence["rails"]["params"] = Sanitizer.sanitize_value(filter_params(payload[:params]))
+        end
+
+        # Preserve route template when Rails exposes it (non-lossy structural evidence).
+        route_key = "#{payload[:controller]}##{payload[:action]}"
+        evidence["http"]["route_key"] = route_key if payload[:controller] && payload[:action]
+
+        Auditea.capture(
+          "network.request.completed",
+          category: "network",
+          severity: "info",
+          evidence: evidence,
+          context: {
+            "request_id" => CurrentContext.to_h["request_id"]
+          }.compact,
+          metadata: {
+            "sdk_event_kind" => "auto_observed"
+          }
+        )
+      rescue StandardError => error
+        Auditea.handle_error(error)
+      end
+
+      def filter_params(params)
+        hash = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
+        hash.except("controller", "action")
+      rescue StandardError
+        {}
+      end
+
+      def request_method(payload)
+        request = payload[:request]
+        return unless request.respond_to?(:request_method)
+
+        request.request_method
+      end
+    end
+  end
+end

data/lib/auditea/log.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Log
+    LEVELS = {
+      "debug" => "debug",
+      "info" => "info",
+      "warn" => "warn",
+      "warning" => "warn",
+      "error" => "error",
+      "fatal" => "fatal"
+    }.freeze
+
+    module_function
+
+    def record(level, message, context: {}, metadata: {})
+      normalized = LEVELS[level.to_s.downcase] || "info"
+      text = Sanitizer.truncate_string(message.to_s, Auditea.configuration.message_max_bytes)
+
+      Auditea.capture(
+        "log.recorded",
+        category: "log",
+        severity: normalized,
+        context: context,
+        evidence: {
+          "log" => {
+            "message" => text,
+            "level" => normalized
+          }
+        },
+        metadata: metadata
+      )
+    end
+  end
+end

data/lib/auditea/middleware/context.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Middleware
+    # Rack middleware: sets CurrentContext with safe structural request fields.
+    # Does NOT store session_id, cookies, Authorization, or query strings.
+    class Context
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        CurrentContext.clear!
+        request = ::Rack::Request.new(env)
+        CurrentContext.set(
+          "request_id" => env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"],
+          "http" => {
+            "method" => request.request_method,
+            "path" => path_without_query(request)
+          }
+        )
+        @app.call(env)
+      ensure
+        CurrentContext.clear!
+      end
+
+      private
+
+      def path_without_query(request)
+        path = request.path.to_s
+        path.split("?", 2).first
+      end
+    end
+  end
+end

data/lib/auditea/railtie.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Auditea
+  class Railtie < ::Rails::Railtie
+    initializer "auditea.configure" do
+      Auditea.configuration.logger = Rails.logger if Rails.logger
+      begin
+        Auditea.configuration.validate!
+      rescue Auditea::ConfigurationError => error
+        Rails.logger&.warn("[auditea] configuration warning: #{error.message}")
+      end
+    end
+
+    initializer "auditea.middleware" do |app|
+      app.middleware.use Auditea::Middleware::Context
+    end
+
+    initializer "auditea.instrumentation" do
+      Auditea::Instrumentation::Request.install!
+      Auditea::Instrumentation::ActiveJob.install!
+    end
+
+    config.after_initialize do
+      at_exit { Auditea.shutdown }
+    end
+  end
+end

data/lib/auditea/sanitizer.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Auditea
+  # Client-side sanitization before enqueue (server also filters).
+  # Never auto-include credentials, cookies, authorization, or raw bodies.
+  # Exact normalized key matching only (no substring matches).
+  module Sanitizer
+    FILTERED = "[FILTERED]"
+    SENSITIVE_KEYS = %w[
+      password password_confirmation password_digest authorization cookie set_cookie
+      api_key access_token refresh_token secret secret_key client_secret private_key token
+      otp otp_secret session_id credit_card card_number cvv ssn
+    ].freeze
+
+    module_function
+
+    def sanitize_event(event)
+      redacted = []
+      sanitized = deep_sanitize(event, depth: 0, path: nil, redacted: redacted)
+      return sanitized unless sanitized.is_a?(Hash)
+
+      merge_redacted_fields!(sanitized, redacted)
+      sanitized
+    end
+
+    def sanitize_value(value, depth: 0)
+      deep_sanitize(value, depth: depth, path: nil, redacted: [])
+    end
+
+    def normalize_key(key)
+      key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').tr("-", "_").downcase
+    end
+
+    def sensitive_key?(key)
+      SENSITIVE_KEYS.include?(normalize_key(key))
+    end
+
+    def truncate_string(value, max_bytes)
+      string = value.to_s
+      return string if string.bytesize <= max_bytes
+
+      "#{string.byteslice(0, max_bytes)}…"
+    end
+
+    def deep_sanitize(value, depth:, path:, redacted:)
+      cfg = Auditea.configuration
+      return { "truncated" => true, "reason" => "max_depth" } if depth > cfg.nesting_max_depth
+
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, child), memo|
+          key_s = key.to_s
+          child_path = path ? "#{path}.#{key_s}" : key_s
+          if sensitive_key?(key)
+            memo[key_s] = FILTERED
+            redacted << child_path if redacted
+          else
+            memo[key_s] = deep_sanitize(child, depth: depth + 1, path: child_path, redacted: redacted)
+          end
+        end
+      when Array
+        value.first(100).each_with_index.map do |child, index|
+          child_path = path ? "#{path}[#{index}]" : "[#{index}]"
+          deep_sanitize(child, depth: depth + 1, path: child_path, redacted: redacted)
+        end
+      when String
+        truncate_string(value, cfg.message_max_bytes)
+      when Numeric, TrueClass, FalseClass, NilClass
+        value
+      else
+        truncate_string(value.inspect, cfg.message_max_bytes)
+      end
+    end
+
+    def merge_redacted_fields!(event, redacted)
+      return if redacted.nil? || redacted.empty?
+
+      privacy = event["privacy"]
+      privacy = privacy.is_a?(Hash) ? privacy.dup : {}
+      existing = Array(privacy["redacted_fields"]).map(&:to_s)
+      privacy["redacted_fields"] = (existing + redacted).uniq
+      event["privacy"] = privacy
+    end
+  end
+end

data/lib/auditea/target.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Target
+    module_function
+
+    def from_record(record, type: nil)
+      return nil unless record
+
+      {
+        "type" => type || record.class&.name,
+        "id" => safe(record, :id) || safe(record, :to_param)
+      }.compact
+    end
+
+    def safe(object, method_name)
+      return nil unless object.respond_to?(method_name)
+
+      value = object.public_send(method_name)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?) ? nil : value.to_s
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/auditea/transport/delivery_result.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Transport
+    # Structured delivery outcome. Fail-open to the host app does not imply
+    # that a rejected event was "delivered successfully".
+    class DeliveryResult
+      ATTRS = %i[
+        ok status outcome event_id permanent retryable message body results
+      ].freeze
+
+      attr_reader(*ATTRS)
+
+      def initialize(ok:, outcome:, status: nil, event_id: nil, permanent: false,
+                     retryable: false, message: nil, body: nil, results: nil)
+        @ok = ok
+        @status = status
+        @outcome = outcome.to_sym
+        @event_id = event_id
+        @permanent = permanent
+        @retryable = retryable
+        @message = message
+        @body = body
+        @results = results
+      end
+
+      def ok?
+        !!@ok
+      end
+
+      def permanent?
+        !!@permanent
+      end
+
+      def retryable?
+        !!@retryable
+      end
+
+      def to_h
+        {
+          ok: ok?,
+          status: status,
+          outcome: outcome,
+          event_id: event_id,
+          permanent: permanent?,
+          retryable: retryable?,
+          message: message,
+          results: results
+        }.compact
+      end
+
+      def self.success(status:, outcome:, event_id: nil, body: nil, results: nil)
+        new(ok: true, status: status, outcome: outcome, event_id: event_id,
+            permanent: false, retryable: false, body: body, results: results)
+      end
+
+      def self.permanent_failure(status:, outcome:, event_id: nil, message: nil, body: nil, results: nil)
+        new(ok: false, status: status, outcome: outcome, event_id: event_id,
+            permanent: true, retryable: false, message: message, body: body, results: results)
+      end
+
+      def self.transient_failure(outcome:, status: nil, message: nil, event_id: nil)
+        new(ok: false, status: status, outcome: outcome, event_id: event_id,
+            permanent: false, retryable: true, message: message)
+      end
+    end
+  end
+end