fiber_audit 0.1.0 → 0.2.0

data/lib/fiber_audit/errors.rb

@@ -5,4 +5,6 @@ module FiberAudit
   class EmptyEvidenceError < StandardError; end
   class ReporterError < StandardError; end
   class ProjectError < StandardError; end
+  class RuntimeContractError < ArgumentError; end
+  class RuntimeSafetyError < StandardError; end
 end

data/lib/fiber_audit/operation_vocabulary.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  # Canonical operation names shared by static findings and runtime evidence.
+  module OperationVocabulary
+    FA1001_TARGETS = {
+      'Kernel' => %i[system exec spawn].freeze,
+      'Open3' => %i[capture2 capture2e capture3 pipeline].freeze,
+      'IO' => %i[popen].freeze,
+      'Process' => %i[waitall detach].freeze
+    }.freeze
+    FA1001_KERNEL_METHODS = %i[system exec spawn].freeze
+
+    FA1002_METHODS = %i[join value].freeze
+    FA1002_OPERATIONS = %w[Thread.join Thread.value].freeze
+
+    FA1003_TARGETS = {
+      'Mutex' => %i[lock synchronize try_lock].freeze,
+      'ConditionVariable' => %i[wait].freeze,
+      'Monitor' => %i[synchronize].freeze,
+      'MonitorMixin' => %i[synchronize].freeze
+    }.freeze
+
+    FA1004_THREAD_VARIABLE_METHODS = %i[thread_variable_get thread_variable_set].freeze
+    FA1004_INDEX_METHODS = %i[[] []=].freeze
+
+    FA1005_TARGETS = {
+      'IO' => :select,
+      'Kernel' => :select
+    }.freeze
+
+    FA1006_EXACT = %w[
+      TCPSocket TCPServer UDPSocket UNIXSocket UNIXServer Socket IPSocket
+    ].freeze
+
+    FA1007_NET_HTTP_METHODS = %i[get get_response start request].freeze
+    FA1007_URI_METHODS = {
+      'URI' => :open,
+      'OpenURI' => :open_uri
+    }.freeze
+  end
+end

data/lib/fiber_audit/reporters/text.rb

@@ -11,7 +11,7 @@ module FiberAudit
     # Calls Schema.build then Schema.validate! to enforce the contract.
     #
     # Exact contract:
-    # - Header: `FiberAudit 0.1.0 — static analysis`
+    # - Header: `FiberAudit <version> — static analysis`
     # - Summary counts, suppressed, status
     # - Disclaimer under status
     # - Findings: RULE  SEVERITY  path:line

data/lib/fiber_audit/runtime/active_operations.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative 'event'
+require_relative 'location'
+require_relative 'validation'
+
+module FiberAudit
+  module Runtime
+    # Bounded process-local registry shared by the watchdog and future probes.
+    class ActiveOperations
+      MAX_ENTRIES = 10_000
+      MAX_SNAPSHOT = 100
+
+      Handle = Data.define(:pid, :thread_id, :fiber_id, :sequence)
+      Entry = Data.define(
+        :thread_id,
+        :fiber_id,
+        :sequence,
+        :operation,
+        :location,
+        :execution_context,
+        :started_monotonic_ns
+      )
+
+      def initialize(pid_source: Process.method(:pid), capacity: MAX_ENTRIES, snapshot_limit: MAX_SNAPSHOT)
+        validate_source!(pid_source)
+        validate_limit!(capacity, 'capacity', MAX_ENTRIES)
+        validate_limit!(snapshot_limit, 'snapshot_limit', MAX_SNAPSHOT)
+        @pid_source = pid_source
+        @capacity = capacity
+        @snapshot_limit = snapshot_limit
+        reset_for_process!(current_pid)
+      end
+
+      def register(
+        operation:,
+        monotonic_ns:,
+        location: nil,
+        execution_context: :unknown,
+        thread: Thread.current,
+        fiber: Fiber.current
+      )
+        ensure_current_process!
+        values = normalize_entry(
+          operation: operation,
+          location: location,
+          execution_context: execution_context,
+          monotonic_ns: monotonic_ns,
+          thread: thread,
+          fiber: fiber
+        )
+
+        @mutex.synchronize do
+          return if @entries.size >= @capacity
+
+          @sequence += 1
+          entry = Entry.new(sequence: @sequence, **values)
+          handle = Handle.new(
+            pid: @owner_pid,
+            thread_id: entry.thread_id,
+            fiber_id: entry.fiber_id,
+            sequence: entry.sequence
+          )
+          @entries[handle] = entry
+          handle
+        end
+      end
+
+      def finish(handle)
+        ensure_current_process!
+        return unless handle.is_a?(Handle) && handle.pid == @owner_pid
+
+        @mutex.synchronize { @entries.delete(handle) }
+      end
+
+      def snapshot(thread_id: nil)
+        ensure_current_process!
+        normalized_thread_id = Validation.integer(thread_id, 'thread_id', allow_nil: true)
+        @mutex.synchronize do
+          entries = @entries.values
+          entries = entries.select { |entry| entry.thread_id == normalized_thread_id } if normalized_thread_id
+          entries.sort_by(&:sequence).first(@snapshot_limit).freeze
+        end
+      end
+
+      def size
+        ensure_current_process!
+        @mutex.synchronize { @entries.size }
+      end
+
+      private
+
+      def normalize_entry(operation:, location:, execution_context:, monotonic_ns:, thread:, fiber:)
+        canonical_operation = Validation.operation(operation)
+        unless location.nil? || location.is_a?(Location)
+          raise RuntimeContractError, 'location must be a FiberAudit::Runtime::Location or nil'
+        end
+
+        normalized_context = execution_context.to_sym if execution_context.is_a?(String) || execution_context.is_a?(Symbol)
+        raise RuntimeContractError, 'execution_context is invalid' unless Context::ALL.include?(normalized_context)
+
+        unless thread.respond_to?(:object_id) && fiber.respond_to?(:object_id)
+          raise RuntimeContractError, 'thread and fiber identities are invalid'
+        end
+
+        {
+          thread_id: Validation.integer(thread.object_id, 'thread_id'),
+          fiber_id: Validation.integer(fiber.object_id, 'fiber_id'),
+          operation: canonical_operation,
+          location: location,
+          execution_context: normalized_context,
+          started_monotonic_ns: Validation.integer(monotonic_ns, 'monotonic_ns')
+        }
+      end
+
+      def ensure_current_process!
+        pid = current_pid
+        reset_for_process!(pid) unless pid == @owner_pid
+      end
+
+      def reset_for_process!(pid)
+        @owner_pid = pid
+        @mutex = Mutex.new
+        @entries = {}
+        @sequence = 0
+      end
+
+      def current_pid
+        value = @pid_source.call
+        return value if value.is_a?(Integer) && value.positive?
+
+        raise RuntimeContractError, 'pid source must return a positive Integer'
+      end
+
+      def validate_source!(source)
+        raise RuntimeContractError, 'pid_source must respond to call' unless source.respond_to?(:call)
+      end
+
+      def validate_limit!(value, name, maximum)
+        return if value.is_a?(Integer) && value.between?(1, maximum)
+
+        raise RuntimeContractError, "#{name} must be an Integer in 1..#{maximum}"
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/boot.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'English'
+require_relative 'environment'
+require_relative 'lifecycle'
+
+module FiberAudit
+  module Runtime
+    module Boot
+      class << self
+        def activate_from_environment!(
+          environment: ENV,
+          clock: Clock.new,
+          session_id_source: SecureRandom.method(:uuid),
+          pid_source: Process.method(:pid),
+          writer_factory: JSONL::Writer.method(:open),
+          random: Sampler::RANDOM_SOURCE
+        )
+          return current if activated_for_current_process?
+
+          mode = Environment.failure_mode(environment)
+          return unless Environment.activated?(environment)
+
+          settings = Environment.load(environment)
+          watchdog_policy = if environment.key?(Environment::WATCHDOG_SETTINGS_KEY)
+                              Environment.load_watchdog_policy(environment)
+                            end
+          @lifecycle = Lifecycle.start(
+            settings: settings,
+            watchdog_policy: watchdog_policy,
+            probes_enabled: Environment.probes_enabled?(environment),
+            clock: clock,
+            session_id_source: session_id_source,
+            pid_source: pid_source,
+            writer_factory: writer_factory,
+            random: random
+          )
+          @pid_source = pid_source
+          @activation_pid = pid_source.call
+          install_shutdown_hook!
+          @lifecycle
+        rescue StandardError
+          raise if defined?(mode) && mode == :closed
+
+          nil
+        end
+
+        def current
+          return unless @lifecycle
+
+          @lifecycle.ensure_current_process!
+          @activation_pid = @pid_source.call
+          @lifecycle
+        end
+
+        def activated?
+          !current.nil?
+        end
+
+        def shutdown(exception: nil)
+          current&.shutdown(exception: exception)
+        end
+
+        private
+
+        def activated_for_current_process?
+          return false unless @lifecycle && @pid_source && @activation_pid
+
+          @activation_pid == @pid_source.call
+        end
+
+        def install_shutdown_hook!
+          return if @shutdown_hook_installed
+
+          at_exit { FiberAudit::Runtime::Boot.shutdown(exception: $ERROR_INFO) }
+          @shutdown_hook_installed = true
+        end
+      end
+    end
+  end
+end
+
+FiberAudit::Runtime::Boot.activate_from_environment! if ENV.key?(FiberAudit::Runtime::Environment::ACTIVATION_KEY)

data/lib/fiber_audit/runtime/clock.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'validation'
+
+module FiberAudit
+  module Runtime
+    class Clock
+      MAX_NANOSECONDS = 9_223_372_036_854_775_807
+      WALL_SOURCE = -> { Time.now }.freeze
+      MONOTONIC_SOURCE = lambda {
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+      }.freeze
+
+      def initialize(wall: WALL_SOURCE, monotonic: MONOTONIC_SOURCE)
+        raise RuntimeContractError, 'wall clock source must respond to call' unless wall.respond_to?(:call)
+        raise RuntimeContractError, 'monotonic clock source must respond to call' unless monotonic.respond_to?(:call)
+
+        @wall = wall
+        @monotonic = monotonic
+        freeze
+      end
+
+      def wall_time
+        Validation.utc_time(@wall.call, 'wall clock result')
+      end
+
+      def monotonic_ns
+        value = Validation.integer(@monotonic.call, 'monotonic clock result')
+        raise RuntimeSafetyError, 'monotonic clock result exceeds signed 64-bit range' if value > MAX_NANOSECONDS
+
+        value
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/environment.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'pathname'
+require 'securerandom'
+require_relative 'policy'
+require_relative 'validation'
+require_relative 'watchdog_policy'
+
+module FiberAudit
+  module Runtime
+    # rubocop:disable Metrics/ModuleLength
+    module Environment
+      PROTOCOL_VERSION = 1
+      ACTIVATION_KEY = 'FIBER_AUDIT_RUNTIME_BOOT'
+      SETTINGS_KEY = 'FIBER_AUDIT_RUNTIME_SETTINGS'
+      FAILURE_MODE_KEY = 'FIBER_AUDIT_RUNTIME_FAILURE_MODE'
+      WATCHDOG_SETTINGS_KEY = 'FIBER_AUDIT_RUNTIME_WATCHDOG_SETTINGS'
+      PROBES_KEY = 'FIBER_AUDIT_RUNTIME_PROBES'
+      BOOT_REQUIRE = '-rfiber_audit/runtime/boot'
+      MAX_SETTINGS_BYTES = 16_384
+      MAX_WATCHDOG_SETTINGS_BYTES = 1_024
+      SETTINGS_KEYS = %w[protocol_version launch_id project_root output_directory policy].freeze
+      POLICY_KEYS = %w[
+        redaction sampling_rate max_events_per_second max_events_per_session
+        max_record_bytes max_session_bytes fail_open
+      ].freeze
+      WATCHDOG_KEYS = %w[
+        protocol_version enabled heartbeat_interval_ms stall_threshold_ms max_frames
+      ].freeze
+
+      Settings = Data.define(:protocol_version, :launch_id, :project_root, :output_directory, :policy) do
+        def initialize(protocol_version:, launch_id:, project_root:, output_directory:, policy:)
+          unless protocol_version == PROTOCOL_VERSION
+            raise RuntimeContractError, "runtime activation protocol must be #{PROTOCOL_VERSION}"
+          end
+          unless launch_id.is_a?(String) && launch_id.match?(Validation::UUID)
+            raise RuntimeContractError, 'runtime launch_id must be a canonical lowercase UUID'
+          end
+          unless policy.is_a?(Policy)
+            raise RuntimeContractError, 'runtime activation policy must be a FiberAudit::Runtime::Policy'
+          end
+
+          super(
+            protocol_version: protocol_version,
+            launch_id: launch_id.dup.freeze,
+            project_root: Environment.normalize_directory(project_root, 'project_root'),
+            output_directory: Environment.normalize_directory(output_directory, 'output_directory'),
+            policy: policy
+          )
+        end
+      end
+
+      module_function
+
+      def build(policy:, output_directory:, project_root:, launch_id: SecureRandom.uuid)
+        Settings.new(
+          protocol_version: PROTOCOL_VERSION,
+          launch_id: launch_id,
+          project_root: project_root,
+          output_directory: output_directory,
+          policy: policy
+        )
+      end
+
+      def dump(settings)
+        require_settings!(settings)
+        payload = {
+          'protocol_version' => settings.protocol_version,
+          'launch_id' => settings.launch_id,
+          'project_root' => settings.project_root,
+          'output_directory' => settings.output_directory,
+          'policy' => policy_payload(settings.policy)
+        }
+        encoded = JSON.generate(payload)
+        raise RuntimeSafetyError, 'runtime activation settings are too large' if encoded.bytesize > MAX_SETTINGS_BYTES
+
+        encoded.freeze
+      end
+
+      def load(environment = ENV)
+        return unless activated?(environment)
+
+        value = environment.fetch(SETTINGS_KEY) do
+          raise RuntimeContractError, "missing runtime activation variable: #{SETTINGS_KEY}"
+        end
+        unless value.is_a?(String) && value.valid_encoding? && value.bytesize <= MAX_SETTINGS_BYTES
+          raise RuntimeContractError, 'runtime activation settings are invalid'
+        end
+
+        payload = JSON.parse(value)
+        require_exact_keys!(payload, SETTINGS_KEYS, 'runtime activation settings')
+        policy_values = payload.fetch('policy')
+        require_exact_keys!(policy_values, POLICY_KEYS, 'runtime activation policy')
+        settings = Settings.new(
+          protocol_version: payload.fetch('protocol_version'),
+          launch_id: payload.fetch('launch_id'),
+          project_root: payload.fetch('project_root'),
+          output_directory: payload.fetch('output_directory'),
+          policy: Policy.new(**symbolize_policy(policy_values))
+        )
+        validate_failure_mode!(environment, settings.policy)
+        settings
+      rescue JSON::ParserError, ArgumentError => e
+        raise RuntimeContractError, "invalid runtime activation settings: #{e.message}"
+      end
+
+      def dump_watchdog_policy(policy)
+        require_watchdog_policy!(policy)
+        payload = {
+          'protocol_version' => PROTOCOL_VERSION,
+          'enabled' => policy.enabled,
+          'heartbeat_interval_ms' => policy.heartbeat_interval_ms,
+          'stall_threshold_ms' => policy.stall_threshold_ms,
+          'max_frames' => policy.max_frames
+        }
+        encoded = JSON.generate(payload)
+        if encoded.bytesize > MAX_WATCHDOG_SETTINGS_BYTES
+          raise RuntimeSafetyError, 'runtime watchdog activation settings are too large'
+        end
+
+        encoded.freeze
+      end
+
+      def load_watchdog_policy(environment = ENV)
+        value = environment[WATCHDOG_SETTINGS_KEY]
+        return WatchdogPolicy::DISABLED if value.nil?
+        unless value.is_a?(String) && value.valid_encoding? && value.bytesize <= MAX_WATCHDOG_SETTINGS_BYTES
+          raise RuntimeContractError, 'runtime watchdog activation settings are invalid'
+        end
+
+        payload = JSON.parse(value)
+        require_exact_keys!(payload, WATCHDOG_KEYS, 'runtime watchdog activation settings')
+        unless payload.fetch('protocol_version') == PROTOCOL_VERSION
+          raise RuntimeContractError, "runtime watchdog activation protocol must be #{PROTOCOL_VERSION}"
+        end
+
+        WatchdogPolicy.new(
+          enabled: payload.fetch('enabled'),
+          heartbeat_interval_ms: payload.fetch('heartbeat_interval_ms'),
+          stall_threshold_ms: payload.fetch('stall_threshold_ms'),
+          max_frames: payload.fetch('max_frames')
+        )
+      rescue JSON::ParserError, ArgumentError => e
+        raise RuntimeContractError, "invalid runtime watchdog activation settings: #{e.message}"
+      end
+
+      def activated?(environment = ENV)
+        marker = environment[ACTIVATION_KEY]
+        return false if marker.nil?
+        return true if marker == '1'
+
+        raise RuntimeContractError, "#{ACTIVATION_KEY} must be 1"
+      end
+
+      def failure_mode(environment = ENV)
+        value = environment[FAILURE_MODE_KEY]
+        return :open if value.nil? || value == 'open'
+        return :closed if value == 'closed'
+
+        raise RuntimeContractError, "#{FAILURE_MODE_KEY} must be open or closed"
+      end
+
+      def probes_enabled?(environment = ENV)
+        value = environment[PROBES_KEY]
+        return false if value.nil?
+        return true if value == '1'
+
+        raise RuntimeContractError, "#{PROBES_KEY} must be 1 when present"
+      end
+
+      def child_environment(
+        settings:,
+        watchdog_policy: nil,
+        probes_enabled: false,
+        base_environment: ENV,
+        library_path: default_library_path
+      )
+        require_settings!(settings)
+        require_watchdog_policy!(watchdog_policy) if watchdog_policy
+        raise RuntimeContractError, 'probes_enabled must be a Boolean' unless [true, false].include?(probes_enabled)
+        raise RuntimeContractError, 'base_environment must be a Hash-like object' unless base_environment.respond_to?(:[])
+
+        environment = {
+          ACTIVATION_KEY => '1',
+          SETTINGS_KEY => dump(settings),
+          FAILURE_MODE_KEY => settings.policy.fail_open? ? 'open' : 'closed',
+          'RUBYOPT' => prepend_token(base_environment['RUBYOPT'], BOOT_REQUIRE, separator: ' '),
+          'RUBYLIB' => prepend_token(base_environment['RUBYLIB'], library_path, separator: File::PATH_SEPARATOR)
+        }
+        environment[WATCHDOG_SETTINGS_KEY] = dump_watchdog_policy(watchdog_policy) if watchdog_policy
+        environment[PROBES_KEY] = '1' if probes_enabled
+        environment.transform_values(&:freeze).freeze
+      end
+
+      def prepare_output_directory(path)
+        normalized = normalize_absolute_path(path, 'output directory')
+        if File.exist?(normalized)
+          raise RuntimeSafetyError, "runtime output is not a directory: #{normalized}" unless File.directory?(normalized)
+
+          return normalized
+        end
+
+        FileUtils.mkdir_p(normalized, mode: 0o700)
+        File.chmod(0o700, normalized)
+        normalized
+      rescue SystemCallError => e
+        raise RuntimeSafetyError, "cannot prepare runtime output directory: #{e.message}"
+      end
+
+      def normalize_directory(value, field)
+        normalized = normalize_absolute_path(value, field)
+        raise RuntimeContractError, "#{field} must be an existing directory" unless File.directory?(normalized)
+
+        normalized.freeze
+      end
+
+      def default_library_path
+        File.expand_path('../..', __dir__).freeze
+      end
+      private_class_method :default_library_path
+
+      def normalize_absolute_path(value, field)
+        text = Validation.string(value, field, max_bytes: 4_096)
+        path = Pathname.new(text)
+        raise RuntimeContractError, "#{field} must be absolute" unless path.absolute?
+
+        path.cleanpath.to_s.freeze
+      rescue ArgumentError
+        raise RuntimeContractError, "#{field} is invalid"
+      end
+      private_class_method :normalize_absolute_path
+
+      def prepend_token(existing, token, separator:)
+        current = existing.to_s
+        parts = current.split(separator)
+        return current.dup.freeze if parts.include?(token)
+
+        current.empty? ? token.dup.freeze : "#{token}#{separator}#{current}".freeze
+      end
+      private_class_method :prepend_token
+
+      def require_settings!(value)
+        return if value.is_a?(Settings)
+
+        raise RuntimeContractError, 'settings must be FiberAudit::Runtime::Environment::Settings'
+      end
+      private_class_method :require_settings!
+
+      def require_watchdog_policy!(value)
+        return if value.is_a?(WatchdogPolicy)
+
+        raise RuntimeContractError, 'watchdog_policy must be FiberAudit::Runtime::WatchdogPolicy'
+      end
+      private_class_method :require_watchdog_policy!
+
+      def require_exact_keys!(value, expected, path)
+        raise RuntimeContractError, "#{path} must be an object" unless value.is_a?(Hash)
+
+        unknown = value.keys - expected
+        missing = expected - value.keys
+        raise RuntimeContractError, "unknown key #{unknown.first.inspect} at #{path}" unless unknown.empty?
+        raise RuntimeContractError, "missing key #{missing.first.inspect} at #{path}" unless missing.empty?
+      end
+      private_class_method :require_exact_keys!
+
+      def policy_payload(policy)
+        policy.to_h.transform_values { |value| value.is_a?(Symbol) ? value.to_s : value }.transform_keys(&:to_s)
+      end
+      private_class_method :policy_payload
+
+      def symbolize_policy(values)
+        values.to_h { |key, value| [key.to_sym, value] }
+      end
+      private_class_method :symbolize_policy
+
+      def validate_failure_mode!(environment, policy)
+        expected = policy.fail_open? ? :open : :closed
+        actual = failure_mode(environment)
+        return if actual == expected
+
+        raise RuntimeContractError, 'runtime activation failure mode does not match policy'
+      end
+      private_class_method :validate_failure_mode!
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end