woods 2.0.0 → 2.1.0

data/lib/woods/source_inputs/stable_reader.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Woods
+  module SourceInputs
+    # Reads bytes only when their descriptor and captured keyed identity agree.
+    # Paths may be captured internal file symlinks, but their resolution must
+    # remain stable and inside the real application root throughout the read.
+    class StableReader
+      DEFAULT_LIMITS = { max_bytes: 8 * 1024 * 1024, max_seconds: 2.0 }.freeze
+
+      class Error < StandardError
+        attr_reader :reason
+
+        def initialize(reason)
+          @reason = reason
+          super
+        end
+      end
+
+      # @param root [String] application root
+      # @param key [PrivateKey] private identity key used by the source snapshot
+      def initialize(root:, key:)
+        @root = File.expand_path(root.to_s)
+        @key = key
+      end
+
+      # Read original bytes without advancing any source-consumption ledger.
+      # The time budget is cooperative between bounded regular-file reads.
+      #
+      # @param path [String] root-relative or absolute application path
+      # @param identity [String] HMAC from the session snapshot
+      # @param max_bytes [Numeric] maximum bytes retained in memory
+      # @param max_seconds [Numeric] maximum elapsed read time
+      # @return [Hash] frozen path, binary source bytes and captured HMAC
+      # @raise [Error] if containment, stability, identity or bounds cannot be proven
+      def read(path, identity:, max_bytes: DEFAULT_LIMITS[:max_bytes], max_seconds: DEFAULT_LIMITS[:max_seconds])
+        @limits = { max_bytes: max_bytes, max_seconds: max_seconds }
+        validate_limits!
+        @started = monotonic
+        absolute = File.expand_path(path.to_s, @root)
+        resolved = resolve(absolute)
+        expected = stamp(File.stat(resolved))
+        source = read_stable(absolute, resolved, expected)
+        actual = OpenSSL::HMAC.hexdigest('SHA256', @key.bytes, source)
+        check_time!
+        raise Error, 'source_snapshot_mismatch' unless actual == identity
+
+        { 'path' => absolute.delete_prefix("#{@root}/").freeze, 'source' => source.freeze,
+          'identity' => identity.dup.freeze }
+      rescue SystemCallError, IOError
+        raise Error, 'source_file_unreadable'
+      end
+
+      private
+
+      def validate_limits!
+        return if @limits.values.all? { |value| value.is_a?(Numeric) && value.finite? && value.positive? }
+
+        raise ArgumentError, 'source read limits must be finite and positive'
+      end
+
+      def resolve(path)
+        raise Error, 'source_outside_root' unless path.start_with?("#{@root}/")
+
+        @resolved_root = File.realpath(@root)
+        resolved = File.realpath(path)
+        raise Error, 'source_outside_root' unless resolved.start_with?("#{@resolved_root}/")
+
+        resolved
+      end
+
+      def read_stable(path, resolved, expected)
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(resolved, flags) do |file|
+          file.binmode
+          before = stamp(file.stat)
+          raise Error, 'nonregular_source' unless file.stat.file?
+          raise Error, 'source_changed_during_read' unless before == expected && stable_path?(path, resolved)
+          raise Error, 'source_read_byte_budget' if file.stat.size > @limits[:max_bytes]
+
+          source = read_bytes(file)
+          verify_after!(file, before, path, resolved)
+          source
+        end
+      end
+
+      def verify_after!(file, before, path, resolved)
+        return if before == stamp(file.stat) && before == stamp(File.stat(resolved)) && stable_path?(path, resolved)
+
+        raise Error, 'source_changed_during_read'
+      end
+
+      def read_bytes(file)
+        source = String.new(encoding: Encoding::BINARY)
+        loop do
+          check_time!
+          chunk = file.read(16_384)
+          break unless chunk
+          raise Error, 'source_read_byte_budget' if source.bytesize + chunk.bytesize > @limits[:max_bytes]
+
+          source << chunk
+        end
+        check_time!
+        source
+      end
+
+      def stable_path?(path, resolved)
+        File.realpath(@root) == @resolved_root && File.realpath(path) == resolved
+      end
+
+      def stamp(stat)
+        [stat.dev, stat.ino, stat.size, stat.mtime.to_r, stat.ctime.to_r]
+      end
+
+      def check_time!
+        raise Error, 'source_read_time_budget' if monotonic - @started > @limits[:max_seconds]
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/woods/source_inputs/status.rb

@@ -12,6 +12,13 @@ module Woods
       BUDGETS = { 'quick' => 0.25, 'deep' => 5.0 }.freeze
 
       def self.from_transport(encoded)
+        options = transport_options(encoded)
+        new(output_dir: options.fetch('output', ENV.fetch('WOODS_OUTPUT', 'tmp/woods')),
+            root: options.fetch('root', Dir.pwd), mode: options.fetch('mode', 'quick')).call
+          .merge('root_source' => options.key?('root') ? 'explicit' : 'working_directory')
+      end
+
+      def self.transport_options(encoded)
         raise ArgumentError, 'source status options are too large' if encoded.to_s.bytesize > 16_384
 
         options = encoded.nil? ? {} : JSON.parse(Base64.strict_decode64(encoded))
@@ -19,20 +26,21 @@ module Woods
           raise ArgumentError, 'source status options must contain only output, root and mode strings'
         end
 
-        new(output_dir: options.fetch('output', ENV.fetch('WOODS_OUTPUT', 'tmp/woods')),
-            root: options['root'], mode: options.fetch('mode', 'quick')).call
+        options
       rescue JSON::ParserError
         raise ArgumentError, 'invalid source status options'
       end
 
+      private_class_method :transport_options
+
       def initialize(output_dir:, payload_dir: nil, generation: nil, root: nil, mode: 'quick')
         raise ArgumentError, 'source status mode must be quick or deep' unless BUDGETS.key?(mode)
 
-        @output = File.expand_path(output_dir.to_s)
-        @root = root
+        @output = SourcePathEncoding.expand(output_dir)
+        @root = SourcePathEncoding.expand(root) if root
         @mode = mode
         @generation = generation
-        @payload = payload_dir
+        @payload = SourcePathEncoding.utf8!(payload_dir) if payload_dir
       end
 
       def call
@@ -46,16 +54,38 @@ module Woods
 
           Manifest.parse(file.read(Manifest::MAX_BYTES + 1))
         end
-        Verifier.new(manifest: manifest, output_dir: @output, root: @root,
-                     generation: @generation, max_seconds: BUDGETS.fetch(@mode)).call.merge('check' => @mode)
+        result = Verifier.new(manifest: manifest, output_dir: @output, root: @root,
+                              generation: @generation, max_seconds: BUDGETS.fetch(@mode)).call
+        result.merge('check' => @mode, 'recommendations' => recommendations(result, manifest))
       rescue Errno::ENOENT
         unknown('source_manifest_unavailable')
       rescue Manifest::Invalid, SystemCallError, IOError
         unknown('invalid_source_manifest')
+      rescue EncodingError, SourcePathEncoding::Invalid
+        unknown('undecodable_source_path')
       end
 
       private
 
+      def recommendations(result, manifest)
+        return ['inspect_source_limits'] if result['state'] == 'unavailable'
+
+        advice = []
+        reader_reasons = result.fetch('verification_reasons', result.fetch('reasons'))
+        if @mode == 'quick' && reader_reasons.include?('scan_time_budget')
+          advice << 'deep_check'
+          reader_reasons -= ['scan_time_budget']
+        end
+        advice << 'inspect_source_scan' unless reader_reasons.empty?
+        advice << 'fresh_capture' if incomplete_capture?(manifest)
+        advice
+      end
+
+      def incomplete_capture?(manifest)
+        !manifest.comparison_complete? || !manifest.data['boot_verified'] ||
+          !manifest.data.fetch('errors').empty? || !manifest.data.fetch('unverified_scopes').empty?
+      end
+
       def resolve_payload
         generation = Generation.new(output_dir: @output)
         marker = if @payload
@@ -77,7 +107,9 @@ module Woods
 
       def unknown(reason)
         { 'state' => 'unknown', 'mode' => 'content', 'check' => @mode, 'generation' => @generation,
-          'checked_at' => Time.now.utc.iso8601, 'complete' => false, 'reasons' => [reason] }
+          'checked_at' => Time.now.utc.iso8601, 'complete' => false, 'reasons' => [reason],
+          'recorded_root' => nil, 'checked_root' => @root, 'root_source' => @root ? 'explicit' : 'recorded',
+          'recommendations' => ['fresh_capture'] }
       end
     end
   end

data/lib/woods/source_inputs/verifier.rb

@@ -16,14 +16,27 @@ module Woods
       def initialize(manifest:, output_dir:, root: nil, generation: nil, max_seconds: DEFAULT_SECONDS, **limits)
         @manifest = manifest.is_a?(Manifest) ? manifest : Manifest.new(manifest)
         @output_dir = output_dir
-        @root = root || @manifest.data.fetch('root')
+        @root = SourcePathEncoding.expand(root || @manifest.data.fetch('root'))
+        @root_source = root ? 'explicit' : 'recorded'
         @generation = generation
         @limits = limits.merge(max_seconds: max_seconds)
       end
 
       # rubocop:enable Metrics/ParameterLists
 
-      def call # rubocop:disable Metrics/AbcSize -- cheap refusal checks precede the only source scan
+      def call
+        result = unavailable_generation? ? unavailable : verify
+        result.merge('recorded_root' => @manifest.data.fetch('root'), 'checked_root' => @root,
+                     'root_source' => @root_source)
+      end
+
+      private
+
+      def unavailable_generation?
+        @manifest.unavailable? && (!@generation || @generation == @manifest.data['generation'])
+      end
+
+      def verify # rubocop:disable Metrics/AbcSize -- cheap refusal checks precede the only source scan
         return unknown('generation_mismatch') if @generation && @generation != @manifest.data['generation']
         return unknown('source_root_unavailable') unless File.directory?(@root)
 
@@ -39,10 +52,10 @@ module Woods
         unknown(e.message)
       rescue SystemCallError, IOError
         unknown('source_root_unavailable')
+      rescue EncodingError, SourcePathEncoding::Invalid
+        unknown('undecodable_source_path')
       end
 
-      private
-
       def compare(current)
         previous = @manifest.expanded
         changes = { 'added' => [], 'changed' => [], 'removed' => [] }
@@ -53,7 +66,7 @@ module Woods
       end
 
       def complete?(current)
-        @manifest.data['complete'] && current['complete']
+        @manifest.comparison_complete? && current['complete']
       end
 
       def compare_scope(scope, paths, changes, current)
@@ -76,6 +89,7 @@ module Woods
         reasons = (@manifest.data.fetch('errors') + current.fetch('errors')).map { |error| error['reason'] }.compact
         reasons << 'incomplete_capture' unless @manifest.data['complete']
         reasons << 'incomplete_verification' unless current['complete']
+        reasons << 'incomplete_comparison_baseline' unless @manifest.comparison_complete?
         reasons << 'unverified_boot_boundary' unless @manifest.data['boot_verified']
         reasons << 'unverified_consumption_scopes' unless @manifest.data.fetch('unverified_scopes').empty?
         reasons.uniq
@@ -86,7 +100,9 @@ module Woods
         counts = changes.transform_values(&:size)
         { 'state' => state_for(counts, reasons), 'mode' => 'content', 'generation' => @manifest.data['generation'],
           'checked_at' => Time.now.utc.iso8601, 'reasons' => reasons,
+          'verification_reasons' => current.fetch('errors').map { |error| error['reason'] }.uniq,
           'complete' => current['complete'] && @manifest.data['complete'],
+          'comparison_complete' => @manifest.comparison_complete?,
           'counts' => counts, 'truncated' => counts.values.any? { |count| count > SUMMARY_LIMIT },
           'changes' => changes.transform_values { |paths| paths.first(SUMMARY_LIMIT) },
           'metrics' => current.fetch('metrics') }
@@ -98,6 +114,13 @@ module Woods
         reasons.empty? ? 'current' : 'unknown'
       end
 
+      def unavailable
+        diagnostic = @manifest.data.fetch('unavailable')
+        { 'state' => 'unavailable', 'mode' => 'content', 'generation' => @manifest.data['generation'],
+          'checked_at' => Time.now.utc.iso8601, 'reasons' => [diagnostic.fetch('reason')],
+          'complete' => false, 'comparison_complete' => false, 'unavailable' => diagnostic }
+      end
+
       def unknown(reason)
         { 'state' => 'unknown', 'mode' => 'content', 'generation' => @manifest.data['generation'],
           'checked_at' => Time.now.utc.iso8601, 'reasons' => [reason], 'complete' => false }

data/lib/woods/source_path_encoding.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Woods
+  # Filesystem encoding tags follow the locale; published source paths use
+  # UTF-8. Validate the original bytes without transcoding or replacing them.
+  module SourcePathEncoding
+    DIAGNOSTIC_BYTES = 256
+    class Invalid < ArgumentError; end
+
+    def self.utf8(path)
+      string = path.to_s
+      string = string.dup.force_encoding(Encoding::UTF_8) unless string.encoding == Encoding::UTF_8
+      string if string.valid_encoding?
+    end
+
+    def self.utf8!(path)
+      utf8(path) || raise(Invalid, 'source paths must contain valid UTF-8 bytes')
+    end
+
+    def self.expand(path)
+      utf8!(File.expand_path(utf8!(path)))
+    end
+
+    # An escaped byte label, never a substituted filesystem path. Bound the
+    # original bytes before escaping, so even malformed deep paths stay small.
+    def self.diagnostic(path)
+      bytes = path.to_s.b
+      label = bytes.byteslice(0, DIAGNOSTIC_BYTES).inspect
+      label += '...' if bytes.bytesize > DIAGNOSTIC_BYTES
+      label
+    end
+  end
+end

data/lib/woods/source_references/cache.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../atomic_file'
+require_relative 'registry'
+
+module Woods
+  module SourceReferences
+    # Generation-local candidate evidence and the edges this pass added. Source
+    # bytes never belong here. Replacing the file must not mutate a hardlinked
+    # seed belonging to the previously published generation.
+    # Keep the closed schema beside its I/O boundary: neither half may accept a
+    # cache that the other half cannot safely publish or replay.
+    class Cache # rubocop:disable Metrics/ClassLength
+      class Invalid < StandardError; end
+
+      # Older JSON parsers pass pairs through #[]=; newer ones must also use
+      # allow_duplicate_key: false before constructing custom objects. A plain
+      # builder avoids optimized Hash writes and returns ordinary consumer data.
+      class UniqueObject
+        attr_reader :data
+
+        def initialize
+          @data = {}
+        end
+
+        def []=(key, value)
+          raise Invalid, 'Source reference cache contains a duplicate JSON key' if @data.key?(key)
+
+          @data[key] = unwrap(value)
+        end
+
+        def unwrap(value)
+          case value
+          when UniqueObject then value.data
+          when Array then value.map { |item| unwrap(item) }
+          else value
+          end
+        end
+      end
+      private_constant :UniqueObject
+
+      FILE_NAME = 'source_references.json'
+      VERSION = 3
+      MAX_BYTES = 64 * 1024 * 1024
+      MAX_FILES = 100_000
+      MAX_OWNERS = 200_000
+      MAX_RECORDS = 1_000_000
+      MAX_NESTING = 128
+      MAX_STRING_BYTES = 4096
+      MAX_LINE = 1_000_000_000
+      IDENTITY = /\A[0-9a-f]{64}\z/
+      TYPES = Registry::TYPES.map(&:to_s).freeze
+      SKIP_REASONS = %w[dynamic_declaration dynamic_superclass dynamic_constant_path unowned_reference
+                        dynamic_singleton_scope dynamic_method_owner].freeze
+
+      class << self
+        # @param path [String, Pathname] cache in one generation payload
+        # @return [Hash, nil] validated evidence, or nil only when absent
+        # @raise [Invalid] unreadable, unsupported or invalid cache
+        def read(path)
+          return unless regular_file?(path)
+
+          data = JSON.parse(read_bytes(path), object_class: UniqueObject, allow_duplicate_key: false)
+          data = data.data if data.is_a?(UniqueObject)
+          validate!(data)
+          data
+        rescue JSON::ParserError, EncodingError, SystemCallError, IOError => e
+          raise Invalid, "Cannot read source reference cache: #{e.class}"
+        end
+
+        # @param path [String, Pathname] destination within the new payload
+        # @param data [Hash] versioned candidate and pass-owned edge evidence
+        # @return [void]
+        # @raise [Invalid] unsupported or invalid cache; previous bytes survive
+        def write(path, data)
+          validate!(data)
+          bytes = JSON.generate(data)
+          raise Invalid, 'Source reference cache exceeds size limit' if bytes.bytesize > MAX_BYTES
+
+          regular_file?(path)
+          AtomicFile.write(path, bytes)
+        rescue JSON::GeneratorError, EncodingError => e
+          raise Invalid, "Cannot encode source reference cache: #{e.class}"
+        end
+
+        private
+
+        def regular_file?(path)
+          stat = File.lstat(path)
+          raise Invalid, 'Source reference cache must be a regular file, not a symlink' unless stat.file?
+
+          true
+        rescue Errno::ENOENT
+          false
+        end
+
+        def read_bytes(path)
+          flags = File::RDONLY | File::NONBLOCK
+          flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+          File.open(path, flags) do |file|
+            raise Invalid, 'Source reference cache must be a regular file' unless file.stat.file?
+            raise Invalid, 'Source reference cache exceeds size limit' if file.stat.size > MAX_BYTES
+
+            bytes = (file.read(MAX_BYTES + 1) || '').force_encoding(Encoding::UTF_8)
+            raise Invalid, 'Source reference cache exceeds size limit' if bytes.bytesize > MAX_BYTES
+            raise Invalid, 'Source reference cache is not UTF-8' unless bytes.valid_encoding?
+
+            bytes
+          end
+        end
+
+        def validate!(data)
+          shape!(data, %w[version files owners])
+          require!(data['version'].instance_of?(Integer) && data['version'] == VERSION, 'unsupported version')
+          files = data['files']
+          require!(files.is_a?(Hash) && files.size <= MAX_FILES, 'invalid files or file limit')
+          records = 0
+          files.each { |path, record| records = bounded_count(records + file!(path, record)) }
+          owners!(data['owners'], files, records)
+        end
+
+        def file!(path, record)
+          path!(path)
+          shape!(record, %w[identity analysis])
+          require!(record['identity'].is_a?(String) && IDENTITY.match?(record['identity']), 'invalid identity')
+          analysis!(record['analysis'])
+        end
+
+        def analysis!(analysis)
+          shape!(analysis, %w[declarations references skipped parse_error])
+          declarations = records!(analysis['declarations'])
+          references = records!(analysis['references'])
+          skipped = records!(analysis['skipped'])
+          total = declarations.size + references.size + skipped.size
+          require!(total <= MAX_RECORDS, 'candidate record limit exceeded')
+          declarations.each { |record| declaration!(record) }
+          references.each { |record| reference!(record) }
+          skipped.each { |record| skipped!(record) }
+          parse_error!(analysis['parse_error'], total)
+          total
+        end
+
+        def declaration!(record)
+          shape!(record, %w[owner name kind nesting enclosing_nesting line end_line], %w[singleton_depth constructor])
+          lexical_record!(record)
+          if record.key?('constructor')
+            require!(record['kind'] == 'class' && %w[Struct ::Struct Data ::Data].include?(record['constructor']),
+                     'invalid value-class constructor')
+          end
+          require!(%w[class module].include?(record['kind']), 'invalid declaration kind')
+          nesting!(record['enclosing_nesting'])
+          line!(record['end_line'])
+          require!(record['end_line'] >= record['line'], 'invalid declaration range')
+        end
+
+        def reference!(record)
+          shape!(record, %w[owner name nesting line], %w[singleton_depth])
+          lexical_record!(record)
+        end
+
+        def lexical_record!(record)
+          constant!(record['owner'])
+          constant!(record['name'], rooted: true)
+          nesting!(record['nesting'])
+          require!(record['nesting'].first == record['owner'], 'owner disagrees with lexical nesting')
+          line!(record['line'])
+          return unless record.key?('singleton_depth')
+
+          depth = record['singleton_depth']
+          require!(depth.instance_of?(Integer) && depth.between?(0, MAX_NESTING), 'invalid singleton depth')
+        end
+
+        def skipped!(record)
+          shape!(record, %w[reason owner line])
+          require!(SKIP_REASONS.include?(record['reason']), 'invalid skip reason')
+          constant!(record['owner']) unless record['owner'].nil?
+          line!(record['line'])
+        end
+
+        def parse_error!(error, total)
+          return if error.nil?
+
+          shape!(error, %w[message line])
+          string!(error['message'])
+          line!(error['line'])
+          require!(total.zero?, 'parse failure contains partial records')
+        end
+
+        def owners!(owners, files, count)
+          require!(owners.is_a?(Array) && owners.size <= MAX_OWNERS, 'invalid owners or owner limit')
+          seen = {}
+          owners.each do |owner|
+            count = bounded_count(count + owner!(owner, files))
+            identity = owner.values_at('type', 'identifier')
+            require!(!seen.key?(identity), 'duplicate owner identity')
+            seen[identity] = true
+          end
+        end
+
+        def owner!(owner, files)
+          shape!(owner, %w[type identifier file_path added], %w[file_paths])
+          type!(owner['type'])
+          constant!(owner['identifier'])
+          path!(owner['file_path'])
+          require!(files.key?(owner['file_path']), 'owner source is absent from files')
+          contributor_paths!(owner, files) if owner.key?('file_paths')
+          edges = records!(owner['added'])
+          edges.each { |edge| edge!(edge) }
+          require!(edges.uniq.size == edges.size, 'duplicate pass-owned edge')
+          edges.size
+        end
+
+        def contributor_paths!(owner, files)
+          paths = owner['file_paths']
+          require!(paths.is_a?(Array) && paths.size > 1 && paths.uniq == paths &&
+                   paths.first == owner['file_path'], 'invalid owner contributors')
+          paths.each do |path|
+            path!(path)
+            require!(files.key?(path), 'owner contributor is absent from files')
+          end
+        end
+
+        def edge!(edge)
+          shape!(edge, %w[type target via])
+          type!(edge['type'])
+          constant!(edge['target'])
+          require!(edge['via'] == 'code_reference', 'invalid pass-owned edge label')
+        end
+
+        def type!(type)
+          require!(TYPES.include?(type), 'invalid constant-owned unit type')
+        end
+
+        def shape!(value, required, optional = [])
+          require!(value.is_a?(Hash), 'invalid record shape')
+          require!((required - value.keys).empty? && (value.keys - required - optional).empty?, 'invalid record keys')
+        end
+
+        def records!(value)
+          require!(value.is_a?(Array) && value.size <= MAX_RECORDS, 'invalid candidate array or record limit')
+          value
+        end
+
+        def bounded_count(count)
+          require!(count <= MAX_RECORDS, 'candidate record limit exceeded')
+          count
+        end
+
+        def nesting!(value)
+          require!(value.is_a?(Array) && value.size <= MAX_NESTING, 'invalid lexical nesting')
+          value.each { |name| constant!(name) }
+        end
+
+        def constant!(value, rooted: false)
+          string!(value)
+          valid = RuntimeLookup::CONSTANT.match?(value) && (rooted || !value.start_with?('::'))
+          require!(valid, 'invalid constant name')
+        end
+
+        def path!(value)
+          string!(value)
+          segments = value.split('/', -1)
+          valid = %w[app lib].include?(segments.first) && segments.size >= 2 && value.end_with?('.rb') &&
+                  !value.include?('\\') && segments.none? { |part| part.empty? || %w[. ..].include?(part) }
+          require!(valid, 'unsafe source path')
+        end
+
+        def string!(value)
+          require!(value.is_a?(String) && value.valid_encoding? && !value.empty? &&
+                   value.bytesize <= MAX_STRING_BYTES && !value.match?(/[\x00-\x1f\x7f]/), 'invalid evidence string')
+        end
+
+        def line!(value)
+          require!(value.instance_of?(Integer) && value.between?(1, MAX_LINE), 'invalid source line')
+        end
+
+        def require!(condition, message)
+          raise Invalid, "Invalid source reference cache: #{message}" unless condition
+        end
+      end
+    end
+  end
+end