woods 2.0.1 → 2.1.0

data/lib/woods/source_contributors.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative 'source_contributor_validation'
+
+module Woods
+  # Provenance for a published unit assembled from several original files.
+  # Byte ranges are half-open and exclude every generated header/separator.
+  module SourceContributors
+    Invalid = SourceContributorValidation::Invalid
+
+    VERSION = 1
+
+    module_function
+
+    # @param unit [ExtractedUnit, Hash]
+    # @return [Array<Hash>] validated, string-keyed contributor records
+    def records(unit)
+      metadata = field(unit, :metadata) || {}
+      raw = field(metadata, :source_contributors)
+      return [] if raw.nil?
+
+      SourceContributorValidation.validate!(raw, type: field(unit, :type),
+                                                 version: field(metadata, :source_contributors_version),
+                                                 source: field(unit, :source_code))
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @return [Array<String>] every physical source, or the legacy primary path
+    def paths(unit)
+      contributors = records(unit)
+      contributors.empty? ? Array(field(unit, :file_path)) : contributors.map { |record| record.fetch('file_path') }
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @return [Boolean]
+    def multiple?(unit)
+      !records(unit).empty?
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @param start_byte [Integer] inclusive published byte offset
+    # @param end_byte [Integer] exclusive published byte offset
+    # @return [Hash, nil] physical coordinates only for an exact original fragment
+    def physical_span(unit, start_byte:, end_byte:)
+      return unless valid_span?(start_byte, end_byte)
+
+      record = records(unit).find do |fragment|
+        start_byte >= fragment['published_start_byte'] && end_byte <= fragment['published_end_byte']
+      end
+      return unless record
+
+      source = field(unit, :source_code)
+      return unless source.is_a?(String)
+
+      first = record['source_start_line'] + source.byteslice(record['published_start_byte']...start_byte).count("\n")
+      { file_path: record['file_path'], source_sha256: record['source_sha256'], start_line: first,
+        end_line: first + source.byteslice(start_byte...end_byte).delete_suffix("\n").count("\n") }
+    end
+
+    def valid_span?(first, last)
+      first.is_a?(Integer) && last.is_a?(Integer) && last > first
+    end
+    private_class_method :valid_span?
+
+    # @param unit [ExtractedUnit, Hash]
+    # @return [String] explicit primary/contributor label, or legacy file label
+    def label(unit)
+      return "File: #{field(unit, :file_path)}" unless multiple?(unit)
+
+      "Primary file: #{field(unit, :file_path)}\nContributing files: #{paths(unit).join(', ')}"
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @return [Hash] additive contributor evidence for response renderers
+    def attribution(unit)
+      multiple?(unit) ? { source_contributors: records(unit) } : {}
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @param resolver [Object] package_for(path) collaborator
+    # @return [String, nil] unanimous package ownership, or nil
+    def annotate_package(unit, resolver)
+      contributors = records(unit)
+      return resolver.package_for(field(unit, :file_path)) if contributors.empty?
+
+      packages = contributors.map do |record|
+        package = resolver.package_for(record['file_path'])
+        package ? record['package'] = package : record.delete('package')
+        package
+      end
+      packages.first if packages.uniq.one?
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @param data [Hash] Git facts keyed by application-relative source path
+    # @return [void]
+    def annotate_git(unit, data)
+      records(unit).each do |record|
+        record.delete('git')
+        record['git'] = data[record['file_path']] if data[record['file_path']]
+      end
+      metadata = field(unit, :metadata)
+      metadata.delete(:git)
+      metadata.delete('git')
+    end
+
+    # @param value [Object, Hash]
+    # @param key [Symbol]
+    # @return [Object]
+    def field(value, key)
+      return value[key] || value[key.to_s] if value.is_a?(Hash)
+
+      value.public_send(key) if value.respond_to?(key)
+    end
+  end
+end

data/lib/woods/source_inputs/handoff.rb

@@ -9,9 +9,35 @@ module Woods
     # existing index manifest nor a user-supplied proof of runtime freshness.
     module Handoff
       ENV_KEY = 'WOODS_SOURCE_CAPTURE'
+      class OutputMismatch < StandardError; end
 
       module_function
 
+      # An implicit preboot default cannot override finalized application config.
+      # Explicit launcher outputs remain intentional overrides. Called before
+      # the writer lock/extraction, while the one-use handoff is still present.
+      # @param root [String, Pathname] finalized application root
+      # @param output_dir [String, Pathname] selected writer output
+      # @return [void]
+      def validate_output!(root:, output_dir:)
+        token = ENV.fetch(ENV_KEY, nil)
+        return if token.to_s.empty?
+
+        descriptor = JSON.parse(token)
+        return unless descriptor.is_a?(Hash) && descriptor['implicit_output'] == true
+
+        expected = File.expand_path('tmp/woods', root.to_s)
+        configured = File.expand_path(Woods.configuration.output_dir.to_s, root.to_s)
+        return if configured == expected && File.expand_path(output_dir.to_s, root.to_s) == expected
+
+        raise OutputMismatch,
+              "woods-extract configured output #{configured.inspect} differs from " \
+              "its preboot default #{expected.inspect}; " \
+              'rerun with matching --output PATH or WOODS_OUTPUT so capture and publication use the same index'
+      rescue JSON::ParserError, TypeError
+        nil # Ordinary handoff validation will refuse unverifiable capture.
+      end
+
       # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       # Every independent handoff binding must match before a token is consumed.
       def read(root:, output_dir:, operation:, rules:, key_id:)
@@ -85,6 +111,17 @@ module Woods
 
       # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
+      # An oversized launcher capture conveys only a downgrade, never proof.
+      def unavailable_evidence
+        descriptor = JSON.parse(ENV.fetch(ENV_KEY, '{}'))
+        value = descriptor.is_a?(Hash) && descriptor['unavailable']
+        return unless Manifest.valid_unavailable_evidence?(value)
+
+        value.slice('reason', 'size_bytes', 'limit_bytes')
+      rescue JSON::ParserError
+        nil
+      end
+
       def extra_roots
         token = ENV.fetch(ENV_KEY, nil)
         return [] if token.nil? || token.empty?

data/lib/woods/source_inputs/launcher.rb

@@ -17,22 +17,27 @@ module Woods
 
       def self.run(argv, **options)
         new(argv, **options).run
-      rescue OptionParser::ParseError, ArgumentError, PrivateKey::Unavailable, SystemCallError => e
+      rescue PrivateKey::Unavailable => e
+        warn "woods-extract: #{e.diagnostic}"
+        1
+      rescue OptionParser::ParseError, ArgumentError, SystemCallError => e
         warn "woods-extract: #{e.message}"
         1
       end
 
-      def initialize(argv, command: %w[bundle exec rake])
+      def initialize(argv, command: nil)
         @arguments = argv.dup
         @command = command
         @original_directory = Dir.pwd
         @root = @original_directory
+        @implicit_output = !ENV.key?('WOODS_OUTPUT')
         @output = ENV.fetch('WOODS_OUTPUT', 'tmp/woods')
         @extra_roots = []
         parse!
+        @command ||= default_command
       end
 
-      def run # rubocop:disable Metrics/MethodLength -- handoff lifetime encloses the fresh child
+      def run
         return 0 if @help
 
         operation, task = task_for_arguments
@@ -40,25 +45,57 @@ module Woods
         rules = Scopes.new(extra_roots: @extra_roots)
         snapshot = Scanner.new(root: @root, output_dir: @output, key: key, scopes: rules).call
         nonce = SecureRandom.hex(32)
+        bytes = capture_bytes(snapshot, nonce, operation, rules)
+        return run_without_capture(task) unless bytes
+
         Tempfile.create(['woods-source-capture-', '.json']) do |file|
           file.binmode
           file.chmod(0o600)
-          file.write(JSON.generate(version: 1, nonce: nonce, root: @root, output: @output,
-                                   operation: operation, rules: rules.fingerprint,
-                                   launcher_pid: Process.pid, snapshot: snapshot))
+          file.write(bytes)
           file.flush
           file.fsync
-          descriptor = JSON.generate(path: file.path, nonce: nonce, extra_roots: @extra_roots)
-          environment = { Handoff::ENV_KEY => descriptor, 'WOODS_OUTPUT' => @output }
-          if ENV['BUNDLE_GEMFILE']
-            environment['BUNDLE_GEMFILE'] = File.expand_path(ENV.fetch('BUNDLE_GEMFILE'), @original_directory)
-          end
-          run_child(environment, task)
+          descriptor = JSON.generate(path: file.path, nonce: nonce, extra_roots: @extra_roots,
+                                     implicit_output: @implicit_output)
+          run_child(child_environment(descriptor), task)
         end
       end
 
       private
 
+      def default_command
+        binstub = File.join(@root, 'bin/rake')
+        File.file?(binstub) && File.executable?(binstub) ? [binstub] : %w[bundle exec rake]
+      end
+
+      def run_without_capture(task)
+        descriptor = JSON.generate(extra_roots: @extra_roots, implicit_output: @implicit_output,
+                                   unavailable: @capture_unavailable)
+        run_child(child_environment(descriptor), task)
+      end
+
+      def capture_bytes(snapshot, nonce, operation, rules)
+        bytes = JSON.generate(version: 1, nonce: nonce, root: @root, output: @output,
+                              operation: operation, rules: rules.fingerprint,
+                              launcher_pid: Process.pid, snapshot: snapshot)
+        return bytes if bytes.bytesize <= Manifest::MAX_BYTES
+
+        @capture_unavailable = { 'reason' => 'source_manifest_too_large', 'size_bytes' => bytes.bytesize,
+                                 'limit_bytes' => Manifest::MAX_BYTES }
+        warn 'woods-extract: source freshness unavailable (source_manifest_too_large): ' \
+             "capture #{bytes.bytesize} bytes exceeds limit #{Manifest::MAX_BYTES}; " \
+             'continuing without verified preboot evidence.'
+        nil
+      end
+
+      def child_environment(descriptor)
+        environment = { Handoff::ENV_KEY => descriptor }
+        environment['WOODS_OUTPUT'] = @output unless @implicit_output
+        if ENV['BUNDLE_GEMFILE']
+          environment['BUNDLE_GEMFILE'] = File.expand_path(ENV.fetch('BUNDLE_GEMFILE'), @original_directory)
+        end
+        environment
+      end
+
       def parse!
         parser.permute!(@arguments)
         validate_arguments! unless @help
@@ -68,7 +105,10 @@ module Woods
         OptionParser.new do |options|
           options.banner = 'Usage: woods-extract [options] full | incremental PATH... | refresh TYPE...'
           options.on('--root PATH', 'Application root (default: current directory)') { |path| @root = path }
-          options.on('--output PATH', 'Index output (default: WOODS_OUTPUT or tmp/woods)') { |path| @output = path }
+          options.on('--output PATH', 'Custom output (default: WOODS_OUTPUT or tmp/woods)') do |path|
+            @output = path
+            @implicit_output = false
+          end
           options.on('--source-root PATH', 'Additional application-relative runtime source root') do |path|
             @extra_roots << path
           end

data/lib/woods/source_inputs/manifest.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'digest'
 
 module Woods
   module SourceInputs
     # Compact wire format: consumers refer to a shared identity table. Internal
     # mutation uses expanded digests so table indices never leak across runs.
-    class Manifest
+    class Manifest # rubocop:disable Metrics/ClassLength -- compact wire validation and bounded serialization
       FILE_NAME = 'source_inputs.json'
       VERSION = 1
       MAX_BYTES = 16 * 1024 * 1024
+      UNKNOWN_BASELINES = %w[invalid_source_baseline missing_or_incompatible_source_baseline
+                             incomplete_source_baseline].freeze
       class Invalid < StandardError; end
 
       attr_reader :data
@@ -34,24 +37,73 @@ module Woods
         end
       end
 
+      # Older version-1 writers encoded missing comparison evidence only as
+      # errors. Never interpret their empty ledger as proof of an empty tree.
+      def comparison_complete?
+        @data['complete'] && @data.fetch('comparison_complete', true) &&
+          @data.fetch('errors').none? { |error| UNKNOWN_BASELINES.include?(error['reason']) }
+      end
+
       # Explicit wire fields keep incomplete coverage separate from boot provenance.
       # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
-      def self.build(snapshot:, scopes:, boot_verified:, generation:, errors: [], unverified_scopes: [])
+      def self.build(snapshot:, scopes:, boot_verified:, generation:, errors: [], unverified_scopes: [],
+                     comparison_complete: true, unavailable: nil)
         identities = scopes.values.flat_map(&:values).uniq.sort
         indices = identities.each_with_index.to_h
         new('version' => VERSION, 'generation' => generation, 'root' => snapshot.fetch('root'),
+            'captured_at' => snapshot['captured_at'],
             'key_id' => snapshot.fetch('key_id'), 'rules' => snapshot.fetch('rules'),
             'extra_roots' => snapshot.fetch('extra_roots'), 'boot_verified' => boot_verified,
             'complete' => snapshot.fetch('complete'), 'errors' => (snapshot.fetch('errors') + errors).uniq,
+            'comparison_complete' => comparison_complete,
             'unverified_scopes' => unverified_scopes.uniq.sort,
             'identities' => identities, 'metrics' => snapshot.fetch('metrics'),
             'scopes' => scopes.sort.to_h.transform_values do |paths|
               paths.sort.to_h.transform_values { |digest| indices.fetch(digest) }
-            end)
+            end).tap { |manifest| manifest.bound_publication!(snapshot: snapshot, unavailable: unavailable) }
       end
 
       # rubocop:enable Metrics/AbcSize, Metrics/ParameterLists
 
+      # Compact watch boundary only: this never certifies runtime freshness.
+      def self.capture_digest(files)
+        Digest::SHA256.hexdigest(JSON.generate(files.sort.to_h))
+      end
+
+      def self.valid_unavailable_evidence?(value)
+        value.is_a?(Hash) && value['reason'] == 'source_manifest_too_large' &&
+          value.values_at('size_bytes', 'limit_bytes').all?(Integer) &&
+          value['limit_bytes'].positive? && value['size_bytes'] > value['limit_bytes']
+      end
+
+      def unavailable?
+        @data['state'] == 'unavailable'
+      end
+
+      # Bind only an already validated, generation-local reference cache. This
+      # preserves its consumed-source proof without publishing the large ledger.
+      def bind_reference_cache!(cache)
+        @data['reference_cache_sha256'] = Digest::SHA256.hexdigest(JSON.generate(cache)) if unavailable? && cache
+      end
+
+      # Source evidence is advisory. Its size limit must not withhold a valid
+      # code index. Keep errors so final publication still refuses unstable input.
+      def bound_publication!(snapshot:, unavailable: nil)
+        size = JSON.pretty_generate(@data).bytesize
+        return unless unavailable || size > MAX_BYTES
+
+        diagnostic = unavailable || { 'reason' => 'source_manifest_too_large',
+                                      'size_bytes' => size, 'limit_bytes' => MAX_BYTES }
+        @data['capture_sha256'] = self.class.capture_digest(snapshot.fetch('files')) if snapshot['complete']
+        @data.merge!('state' => 'unavailable', 'unavailable' => diagnostic,
+                     'complete' => false, 'comparison_complete' => false,
+                     'identities' => [], 'scopes' => {}, 'metrics' => {})
+        warn "[woods] source freshness unavailable: #{diagnostic['reason']}; " \
+             "#{diagnostic['size_bytes']} bytes exceeds limit #{diagnostic['limit_bytes']}. " \
+             'Publishing the code index without freshness comparison evidence; ' \
+             'another full extraction will not reduce this size.'
+      end
+
       private
 
       def validate!
@@ -59,11 +111,28 @@ module Woods
         raise Invalid, 'invalid_source_manifest_header' unless valid_header?
 
         validate_tables!
+        validate_unavailable!
         return if @data['extra_roots'].all? { |path| valid_path?(path) }
 
         raise Invalid, 'invalid_source_roots'
       end
 
+      def validate_unavailable!
+        return if (%w[state unavailable reference_cache_sha256 capture_sha256] & @data.keys).empty?
+
+        valid = unavailable? && self.class.valid_unavailable_evidence?(@data['unavailable']) && empty_comparison?
+        valid &&= valid_optional_digests?
+        raise Invalid, 'invalid_unavailable_source_manifest' unless valid
+      end
+
+      def valid_optional_digests?
+        %w[reference_cache_sha256 capture_sha256].all? { |key| !@data.key?(key) || digest?(@data[key]) }
+      end
+
+      def empty_comparison?
+        !@data['complete'] && !@data['comparison_complete'] && @data['scopes'].empty? && @data['identities'].empty?
+      end
+
       def validate_tables!
         identities = @data['identities']
         scopes = @data['scopes']
@@ -89,9 +158,21 @@ module Woods
 
       def valid_header?
         valid_root? && %w[key_id rules].all? { |key| digest?(@data[key]) } &&
+          valid_capture_time? && valid_comparison_coverage? &&
           %w[boot_verified complete].all? { |key| [true, false].include?(@data[key]) }
       end
 
+      def valid_comparison_coverage?
+        !@data.key?('comparison_complete') || [true, false].include?(@data['comparison_complete'])
+      end
+
+      # Optional so existing version-1 manifests remain readable. Consumers
+      # needing a catch-up boundary must reconcile when it is absent.
+      def valid_capture_time?
+        value = @data['captured_at']
+        value.nil? || (value.is_a?(Numeric) && value.finite? && value.positive?)
+      end
+
       def valid_root?
         root = @data['root']
         root.is_a?(String) && root.start_with?('/') && !root.include?("\0")

data/lib/woods/source_inputs/private_key.rb

@@ -10,30 +10,62 @@ module Woods
     # for ordinary source, so an unrecognized secret-bearing file stays protected.
     class PrivateKey
       FILE_NAME = '.source-inputs.key'
-      class Unavailable < StandardError; end
+      class Unavailable < StandardError
+        def initialize(reason, path: nil, detail: nil)
+          super(reason)
+          @path = path
+          @detail = detail
+        end
+
+        # Keep the machine-readable reason unchanged for freshness readers.
+        # @return [String] safe launcher diagnostic without key bytes
+        def diagnostic
+          "#{message}: #{@path.inspect}: #{@detail}. " \
+            'Verify the owner UID and mount permissions in the application environment; ' \
+            'use an owner-only regular 32-byte key. Woods did not repair or rotate it. ' \
+            'See docs/SOURCE_FRESHNESS.md#identity-key-recovery.'
+        end
+      end
 
       attr_reader :bytes, :identifier
 
       def initialize(output_dir:, create: false)
-        path = File.join(output_dir.to_s, FILE_NAME)
+        path = File.expand_path(File.join(output_dir.to_s, FILE_NAME))
         create_key(path) if create
-        flags = File::RDONLY | File::NONBLOCK
-        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
-        File.open(path, flags) do |file|
-          stat = file.stat
-          raise Unavailable, 'insecure_identity_key' unless private_regular?(stat)
-
-          @bytes = file.read(33)
+        @bytes = read_key(path)
+        unless @bytes&.bytesize == 32
+          raise Unavailable.new('invalid_identity_key', path: path, detail: 'expected exactly 32 bytes')
         end
-        raise Unavailable, 'invalid_identity_key' unless @bytes&.bytesize == 32
 
         @identifier = Digest::SHA256.hexdigest(@bytes)
-      rescue SystemCallError, IOError
-        raise Unavailable, 'identity_key_unavailable'
+      rescue SystemCallError, IOError => e
+        raise Unavailable.new(
+          'identity_key_unavailable',
+          path: path,
+          detail: "cannot safely open a regular non-symlink key (#{e.class})"
+        )
       end
 
       private
 
+      # @param path [String] private identity-key path
+      # @return [String] bounded key bytes after safe descriptor validation
+      def read_key(path)
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(path, flags) do |file|
+          unless private_regular?(file.stat)
+            raise Unavailable.new(
+              'insecure_identity_key',
+              path: path,
+              detail: 'expected a regular file owned by this UID with owner-only permissions'
+            )
+          end
+
+          file.read(33)
+        end
+      end
+
       def private_regular?(stat)
         stat.file? && stat.uid == Process.uid && stat.mode.nobits?(0o077)
       end