haveapi-client 0.30.2 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c1db16e3a0212003b9eb0295ce126c0d7eabb2a467b970680b73dcad43540d8
-  data.tar.gz: b56c37f31b2e8fe7c0455d2a77d99b9644ca8e7328016227c81b9f3d12daa549
+  metadata.gz: a038ddc787fd511c462c3726c76879d2e681e5db46bb4ea45c9892a7827f9d2e
+  data.tar.gz: ca3e1618fbb4a2e1b072d8840d485043ce4b3b3642cdc2e90b5360246e8ed185
 SHA512:
-  metadata.gz: 77374baf3f68a17d93e2114f890566bb2842521de475937e6ab031f56ade293ccb6d83ff785b9742966301a1a3748bf6c96768a6c52e7e5ee16c85a0dc3c9534
-  data.tar.gz: fcdeab4afab35236ecb439caf9a52f2ecfe132226ef55bfdaecacc7bd684552209a2ff670cf8ebb6278bd755ada599a5407a2bd5631c06fb8214cd9326709d9f
+  metadata.gz: 1473dc78ee53f54123b94354190977141fe1f9888f11d401ec278bf09ae695c4b9ae5766503af504bd95cce19027d3a790eaae3444e4ed28b0038b3124716be2
+  data.tar.gz: cf0f6f0aeb4fd55c9f7053d32db1b273de8a903d9c371be75d086ed180e314ba7b3bbcbfe2e32be3dac4cf5a1d3454b8d3e35377ee388983f3fde313dca3d3bb

data/lib/haveapi/client/version.rb

@@ -1,6 +1,6 @@
 module HaveAPI
   module Client
     PROTOCOL_VERSION = '2.0'.freeze
-    VERSION = '0.30.2'.freeze
+    VERSION = '0.31.0'.freeze
   end
 end

data/lib/haveapi/schema/capture.rb

@@ -0,0 +1,81 @@
+module HaveAPI::Schema
+  module Capture
+    def self.fetch(url:, api_version:, profile:, basic_user: nil, basic_password: nil, token: nil, diagnostics: [])
+      mount = validate_options(url: url, api_version: api_version, profile: profile,
+                               basic_user: basic_user, basic_password: basic_password, token: token)
+      begin
+        require 'rest-client'
+      rescue LoadError
+        raise Error, 'capture dependencies are unavailable; prepare the haveapi-client bundle', cause: nil
+      end
+
+      headers = { accept: :json }
+      if token
+        discovery = snapshot(request(url, headers), url, api_version, profile, mount, [])
+        provider = discovery.fetch('description').fetch('authentication')['token']
+        raise Error, 'API does not advertise HaveAPI token authentication' unless provider.is_a?(Hash)
+
+        headers = headers.merge(token_headers(provider, token))
+      end
+      snapshot(request(url, headers, basic_user, basic_password), url, api_version, profile, mount, diagnostics)
+    end
+
+    def self.validate_options(url:, api_version:, profile:, basic_user: nil, basic_password: nil, token: nil)
+      Snapshot.version!(api_version)
+      endpoint = Snapshot.endpoint!(url)
+      suffix = "v#{api_version}/"
+      unless endpoint.path.end_with?("/#{suffix}")
+        raise Error, 'fetch URL must select the exact requested version'
+      end
+      raise Error, 'profile must be a nonempty label' unless profile.is_a?(String) && !profile.strip.empty?
+      if !token.nil? && (!basic_user.nil? || !basic_password.nil?)
+        raise Error, 'Basic and token authentication are mutually exclusive'
+      end
+
+      if (!basic_user.nil? || !basic_password.nil?) && !(credential?(basic_user) && !basic_user.include?(':') && credential?(basic_password))
+        raise Error, 'Basic authentication requires a valid user and password'
+      end
+      raise Error, 'existing token must be a nonempty header value' if !token.nil? && !credential?(token)
+
+      endpoint.path.delete_suffix(suffix)
+    end
+
+    def self.credential?(value)
+      value.is_a?(String) && !value.empty? && !value.match?(/[\x00-\x1f\x7f]/)
+    end
+
+    def self.request(url, headers, basic_user = nil, basic_password = nil)
+      options = {
+        method: :options, url: url, headers: headers, verify_ssl: true,
+        max_redirects: 0, open_timeout: 10, read_timeout: 30
+      }
+      options.update(user: basic_user, password: basic_password) if basic_user
+      response = RestClient::Request.execute(options)
+      unless response.code >= 200 && response.code < 300
+        raise Error, 'metadata acquisition failed (HTTP or redirect error)'
+      end
+
+      JSON.parse(response.to_s)
+    rescue StandardError
+      raise Error, 'metadata acquisition failed (HTTP, redirect or response error)', cause: nil
+    end
+
+    def self.snapshot(envelope, url, version, profile, mount, diagnostics)
+      Snapshot.from_envelope(envelope, api_version: version, source_url: url,
+                                       profile: profile, mount_path: mount, diagnostics: diagnostics)
+    rescue Error, ArgumentError, TypeError, NoMethodError
+      raise Error, 'metadata response is not a valid successful protocol 2 description for the requested version', cause: nil
+    end
+
+    def self.token_headers(provider, token)
+      # Supplying a token prevents this existing provider from acquiring or renewing one.
+      require 'haveapi/client'
+      HaveAPI::Client::Authentication::Token.new(nil, { http_header: provider['http_header'] }, token: token).request_headers
+    rescue LoadError
+      raise Error, 'capture dependencies are unavailable; prepare the haveapi-client bundle', cause: nil
+    rescue StandardError
+      raise Error, 'API advertises an invalid HaveAPI token HTTP header', cause: nil
+    end
+    private_class_method :credential?, :request, :snapshot, :token_headers
+  end
+end

data/lib/haveapi/schema/fetch_command.rb

@@ -0,0 +1,78 @@
+require 'optparse'
+require 'tempfile'
+
+module HaveAPI::Schema
+  module FetchCommand
+    def self.run(argv, command_name:, out: $stdout, err: $stderr)
+      options = {}
+      args = argv.dup
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: #{command_name} fetch URL --api-version VERSION --profile LABEL --output FILE"
+        opts.on('--api-version VERSION') { |v| options[:api_version] = v }
+        opts.on('--profile LABEL') { |v| options[:profile] = v }
+        opts.on('--output FILE') { |v| options[:output] = v }
+        opts.on('--basic-user USER') { |v| options[:basic_user] = v }
+        opts.on('--basic-password-env ENV_NAME') { |v| options[:password_env] = v }
+        opts.on('--token-env ENV_NAME') { |v| options[:token_env] = v }
+        opts.on('-h', '--help') do
+          out.puts(opts)
+          return 0
+        end
+      end
+      parser.parse!(args)
+      raise Error, 'fetch requires one URL, --api-version, --profile and --output' unless args.length == 1 && options[:output]
+      if options[:token_env] && (options[:basic_user] || options[:password_env])
+        raise Error, 'Basic and token authentication are mutually exclusive'
+      end
+      if options[:basic_user].nil? != options[:password_env].nil?
+        raise Error, 'Basic authentication requires --basic-user and --basic-password-env'
+      end
+
+      request = { url: args.first, api_version: options[:api_version], profile: options[:profile],
+                  basic_user: options[:basic_user], basic_password: secret(options[:password_env]), token: secret(options[:token_env]) }
+      Capture.validate_options(**request)
+      output = File.expand_path(options[:output])
+      validate_output(output)
+      diagnostics = []
+      value = Capture.fetch(**request, diagnostics: diagnostics)
+      bytes = Snapshot.canonical(Snapshot.validate(value))
+      validate_output(output)
+      Tempfile.create(['.haveapi-schema-', '.json'], File.dirname(output)) do |temp|
+        temp.binmode
+        temp.write(bytes)
+        temp.close
+        File.rename(temp.path, output)
+      end
+      diagnostics.each { |message| err.puts(message) }
+      0
+    rescue OptionParser::ParseError
+      err.puts("#{command_name}: invalid fetch arguments; use --help")
+      1
+    rescue Error => e
+      err.puts("#{command_name}: #{e.message}")
+      1
+    rescue SystemCallError, IOError, ArgumentError, TypeError
+      err.puts("#{command_name}: unable to read or save the snapshot")
+      1
+    end
+
+    def self.secret(name)
+      return nil if name.nil?
+      unless name.is_a?(String) && name.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+        raise Error, 'credential environment variable name is invalid'
+      end
+
+      value = ENV.fetch(name, nil)
+      raise Error, 'credential environment variable is missing or empty' unless value && !value.empty?
+
+      value
+    end
+
+    def self.validate_output(path)
+      raise Error, 'snapshot output cannot be a symlink' if File.symlink?(path)
+      raise Error, 'snapshot output parent must already exist' unless File.directory?(File.dirname(path))
+      raise Error, 'snapshot output must be a regular file' if File.exist?(path) && !File.file?(path)
+    end
+    private_class_method :secret, :validate_output
+  end
+end

data/lib/haveapi/schema/snapshot.rb

@@ -0,0 +1,203 @@
+require 'json'
+require 'digest'
+require 'uri'
+
+module HaveAPI::Schema
+  module Snapshot
+    KEYS = %w[schema_format api_version protocol_version source_url profile mount_path description].freeze
+    PROSE = %w[description label examples message comment title].freeze
+
+    def self.canonical(value)
+      "#{JSON.pretty_generate(canonical_value(value))}\n"
+    end
+
+    def self.canonical_value(value)
+      case value
+      when Hash
+        value.keys.sort.to_h { |key| [key, canonical_value(value.fetch(key))] }
+      when Array
+        value.map { |item| canonical_value(item) }
+      else
+        value
+      end
+    end
+
+    def self.sha256(snapshot)
+      Digest::SHA256.hexdigest(canonical(snapshot))
+    end
+
+    def self.load(path)
+      validate(JSON.parse(File.read(path)))
+    rescue JSON::ParserError, EncodingError
+      raise Error, 'snapshot is not valid UTF-8 JSON', cause: nil
+    end
+
+    def self.from_envelope(envelope, api_version:, source_url:, profile:, mount_path: '/', diagnostics: [])
+      unless envelope.is_a?(Hash) && envelope['status'] == true
+        raise Error, 'metadata envelope is not successful'
+      end
+
+      from_description(
+        description: envelope.fetch('response'), protocol_version: envelope.fetch('version'),
+        api_version: api_version, source_url: source_url, profile: profile,
+        mount_path: mount_path, diagnostics: diagnostics
+      )
+    rescue KeyError
+      raise Error, 'metadata envelope is incomplete'
+    end
+
+    def self.from_description(description:, api_version:, protocol_version:, source_url:, profile:, mount_path: '/', diagnostics: [])
+      validate({
+        'schema_format' => 1, 'api_version' => api_version, 'protocol_version' => protocol_version,
+        'source_url' => source_url, 'profile' => profile, 'mount_path' => mount_path,
+        'description' => sanitize(description, diagnostics: diagnostics)
+      })
+    end
+
+    # Only structural prose is removed. Custom/default JSON and field names are data.
+    def self.sanitize(value, context = :description, diagnostics: [], path: [])
+      return value.map { |item| sanitize(item, context, diagnostics: diagnostics, path: path) } if value.is_a?(Array)
+      return value unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(key, item), result|
+        next if PROSE.include?(key) && !%i[map data choices].include?(context)
+
+        machine_endpoint!(key, item, path + [key]) if context == :description
+
+        if context == :description && key == 'default' && value['protected'] == true && !item.nil?
+          diagnostics << "removed protected default: #{path.join('/')}"
+          next
+        end
+
+        child = child_context(context, key, item)
+        result[key] = if context == :validators && key == 'custom'
+                        true
+                      elsif context == :choices
+                        nil
+                      else
+                        sanitize(item, child, diagnostics: diagnostics, path: path + [key])
+                      end
+      end
+    end
+
+    def self.child_context(context, key, item)
+      return :data if %i[data choices].include?(context)
+      return :description if context == :map
+      return :map if %w[resources actions parameters authentication].include?(key)
+      return :data if %w[default format].include?(key) && context != :validator
+      return item.is_a?(Hash) ? :choices : :data if key == 'values'
+      return :validators if key == 'validators'
+      return :validator if context == :validators
+
+      :description
+    end
+
+    def self.machine_endpoint!(key, value, path)
+      return if value.nil?
+
+      if key.end_with?('_url')
+        endpoint!(value)
+        return
+      end
+      return unless %w[path help].include?(key) || key.end_with?('_path')
+
+      route, query = value.is_a?(String) ? value.split('?', 2) : [nil, nil]
+      unless route && safe_path?(route) &&
+             (query.nil? || (key == 'help' && query.match?(/\Amethod=(?:GET|POST|PUT|PATCH|DELETE|OPTIONS)\z/)))
+        raise Error, 'unsafe machine endpoint'
+      end
+    rescue Error
+      raise Error, "unsafe machine endpoint at #{path.join('/')}"
+    end
+
+    def self.validate_machine_endpoints(value, context = :description, path = [])
+      if value.is_a?(Array)
+        value.each { |item| validate_machine_endpoints(item, context, path) }
+      elsif value.is_a?(Hash)
+        value.each do |key, item|
+          machine_endpoint!(key, item, path + [key]) if context == :description
+          validate_machine_endpoints(item, child_context(context, key, item), path + [key])
+        end
+      end
+    end
+
+    def self.validate(snapshot)
+      raise Error, 'snapshot must be an object' unless snapshot.is_a?(Hash)
+      raise Error, 'unsupported snapshot envelope keys' unless snapshot.keys.sort == KEYS.sort
+      raise Error, 'unsupported snapshot format' unless snapshot['schema_format'] == 1
+
+      version!(snapshot['api_version'])
+      unless snapshot['protocol_version'].is_a?(String) && snapshot['protocol_version'].match?(/\A2\.\d+\z/)
+        raise Error, 'unsupported HaveAPI protocol major'
+      end
+      unless snapshot['profile'].is_a?(String) && !snapshot['profile'].strip.empty?
+        raise Error, 'profile must be a nonempty label'
+      end
+
+      endpoint = endpoint!(snapshot['source_url'])
+      mount = snapshot['mount_path']
+      unless mount.is_a?(String) && mount.start_with?('/') && mount.end_with?('/') && safe_path?(mount)
+        raise Error, 'invalid capture mount path'
+      end
+
+      expected = "#{mount}v#{snapshot['api_version']}/"
+      raise Error, 'snapshot source URL/version mismatch' unless endpoint.path == expected
+
+      description = snapshot['description']
+      unless description.is_a?(Hash) && description['resources'].is_a?(Hash) &&
+             description['authentication'].is_a?(Hash) && description['meta'].is_a?(Hash)
+        raise Error, 'invalid API description structure'
+      end
+      raise Error, 'snapshot description/version mismatch' unless description['help'] == expected
+
+      description['authentication'].each do |provider, auth|
+        raise Error, "invalid authentication description at authentication/#{provider}" unless auth.is_a?(Hash)
+      end
+      validate_machine_endpoints(description)
+      snapshot
+    end
+
+    def self.version!(version)
+      return if version.is_a?(String) && version.match?(/\A\d+(?:\.\d+)*\z/)
+
+      raise Error, 'an explicit numeric API version is required'
+    end
+
+    def self.endpoint!(url)
+      raise Error, 'invalid endpoint URL' unless url.is_a?(String)
+
+      endpoint = URI.parse(url)
+      unless %w[http https].include?(endpoint.scheme) && endpoint.host && endpoint.userinfo.nil? &&
+             endpoint.query.nil? && endpoint.fragment.nil? && safe_path?(endpoint.path)
+        raise Error, 'endpoint must be an HTTP URL without credentials, query or fragment'
+      end
+
+      endpoint
+    rescue URI::InvalidURIError, TypeError
+      raise Error, 'invalid endpoint URL', cause: nil
+    end
+
+    # Compatibility names used by existing generator facades.
+    def self.sanitization_context(context, key, item)
+      child_context(context, key, item)
+    end
+
+    def self.validate_machine_endpoint(key, value)
+      machine_endpoint!(key, value, [key])
+    end
+
+    def self.safe_segments?(path)
+      return false unless path.is_a?(String)
+
+      safe_path?(path.start_with?('/') ? path : "/#{path}")
+    end
+
+    def self.safe_path?(path)
+      path.is_a?(String) && path.start_with?('/') && !path.start_with?('//') && !path.match?(/[\\?#\x00-\x20\x7f]/) &&
+        path.split('/').none? do |segment|
+          decoded = URI::DEFAULT_PARSER.unescape(segment)
+          %w[. ..].include?(decoded) || decoded.match?(%r{[/\\\x00-\x20\x7f]}) || segment.match?(/%(?![0-9a-fA-F]{2})/)
+        end
+    end
+  end
+end

data/lib/haveapi/schema.rb

@@ -0,0 +1,26 @@
+require 'digest'
+require_relative 'client/version'
+
+module HaveAPI
+  module Schema
+    class Error < StandardError; end
+
+    def self.source_identity
+      root = __dir__
+      digest = Digest::SHA256.new
+      %w[haveapi/client/version.rb haveapi/schema.rb haveapi/schema/capture.rb
+         haveapi/schema/fetch_command.rb haveapi/schema/snapshot.rb].sort.each do |logical|
+        digest.update(logical).update("\0").update(File.binread(File.join(root, '..', logical))).update("\0")
+      end
+      {
+        'package_name' => 'haveapi-client'.freeze,
+        'version' => HaveAPI::Client::VERSION,
+        'source_sha256' => digest.hexdigest.freeze
+      }.freeze
+    end
+  end
+end
+
+require_relative 'schema/snapshot'
+require_relative 'schema/capture'
+require_relative 'schema/fetch_command'

data/spec/schema_capture_spec.rb

@@ -0,0 +1,101 @@
+require_relative 'schema_spec_helper'
+
+RSpec.describe HaveAPI::Schema::Capture do
+  include SchemaFixtures
+
+  before do
+    stub_const('RestClient::Request', Class.new)
+    allow(described_class).to receive(:require).with('rest-client').and_return(true)
+    allow(RestClient::Request).to receive(:execute).and_return(double(code: 200, to_s: JSON.generate(envelope)))
+  end
+
+  def fetch(**options)
+    described_class.fetch(url: SchemaFixtures::URL, api_version: '7.0', profile: 'fixture', **options)
+  end
+
+  it 'requests only the exact mounted version URL with bounded TLS-verified OPTIONS' do
+    expect(fetch).to eq(snapshot)
+    expect(RestClient::Request).to have_received(:execute).once.with(
+      method: :options, url: SchemaFixtures::URL, headers: { accept: :json },
+      verify_ssl: true, max_redirects: 0, open_timeout: 10, read_timeout: 30
+    )
+  end
+
+  it 'uses HTTP Basic credentials without discovery or query parameters' do
+    fetch(basic_user: 'fixture-user', basic_password: 'fixture-password')
+    expect(RestClient::Request).to have_received(:execute).once.with(hash_including(
+                                                                       url: SchemaFixtures::URL, user: 'fixture-user', password: 'fixture-password',
+                                                                       headers: { accept: :json }
+                                                                     ))
+  end
+
+  it 'discovers token policy anonymously at the same URL and saves only the authorized surface' do
+    anonymous = envelope
+    anonymous['response']['authentication'] = { 'token' => { 'http_header' => 'X-Capture-Token' } }
+    authorized = Marshal.load(Marshal.dump(anonymous))
+    authorized['response']['resources'] = { 'authorized' => { 'resources' => {}, 'actions' => {} } }
+    allow(RestClient::Request).to receive(:execute).and_return(
+      double(code: 200, to_s: JSON.generate(anonymous)),
+      double(code: 200, to_s: JSON.generate(authorized))
+    )
+    provider = double(request_headers: { 'X-Capture-Token' => 'fixture-token' })
+    stub_const('HaveAPI::Client::Authentication::Token', Class.new)
+    allow(described_class).to receive(:require).with('haveapi/client').and_return(true)
+    allow(HaveAPI::Client::Authentication::Token).to receive(:new)
+      .with(nil, { http_header: 'X-Capture-Token' }, token: 'fixture-token').and_return(provider)
+    requests = []
+    allow(RestClient::Request).to receive(:execute).and_wrap_original do |_original, options|
+      requests << options
+      body = requests.length == 1 ? anonymous : authorized
+      double(code: 200, to_s: JSON.generate(body))
+    end
+    result = fetch(token: 'fixture-token')
+    expect(HaveAPI::Client::Authentication::Token).to have_received(:new)
+      .with(nil, { http_header: 'X-Capture-Token' }, token: 'fixture-token')
+    expect(requests.map { |r| r.fetch(:url) }).to eq([SchemaFixtures::URL, SchemaFixtures::URL])
+    expect(requests.map { |r| r.fetch(:headers) }).to eq([{ accept: :json }, { accept: :json, 'X-Capture-Token' => 'fixture-token' }])
+    expect(result['description']['resources'].keys).to eq(['authorized'])
+    expect(JSON.generate(result)).not_to include('fixture-token')
+  end
+
+  it 'refuses missing or invalid token discovery before sending the token' do
+    expect { fetch(token: 'fixture-token') }.to raise_error(HaveAPI::Schema::Error, /does not advertise/)
+    expect(RestClient::Request).to have_received(:execute).once
+    anonymous = envelope
+    anonymous['response']['authentication'] = { 'token' => { 'http_header' => "X-Bad\r\nfixture-secret" } }
+    allow(RestClient::Request).to receive(:execute).and_return(double(code: 200, to_s: JSON.generate(anonymous)))
+    stub_const('HaveAPI::Client::Authentication::Token', Class.new)
+    allow(described_class).to receive(:require).with('haveapi/client').and_return(true)
+    allow(HaveAPI::Client::Authentication::Token).to receive(:new).and_raise(ArgumentError, 'fixture-secret')
+    expect { fetch(token: 'fixture-token') }.to raise_error(HaveAPI::Schema::Error) do |error|
+      expect(error.message).to include('invalid HaveAPI token HTTP header')
+      expect(error.full_message).not_to include('fixture-secret', 'fixture-token')
+    end
+    expect(RestClient::Request).to have_received(:execute).twice
+  end
+
+  it 'validates versions, endpoints, profile and exclusive credentials before dispatch' do
+    [
+      { api_version: nil }, { url: 'https://schema.example.test/mount/' }, { profile: '' },
+      { url: 'https://user:fixture-secret@schema.example.test/v7.0/' },
+      { basic_user: 'user' }, { basic_password: 'secret' }, { basic_user: 'a:b', basic_password: 'secret' },
+      { token: false }, { basic_user: false }, { basic_password: false },
+      { token: '' }, { token: "secret\n" }, { token: 'secret', basic_user: 'user', basic_password: 'secret' }
+    ].each do |options|
+      expect { fetch(**options) }.to raise_error(HaveAPI::Schema::Error)
+    end
+    expect(RestClient::Request).not_to have_received(:execute)
+  end
+
+  it 'rejects redirects, transport errors and unsuccessful or incoherent envelopes without leaking bodies' do
+    allow(RestClient::Request).to receive(:execute).and_raise(StandardError, 'fixture-password in raw HTTP error')
+    expect { fetch }.to raise_error(HaveAPI::Schema::Error) { |error| expect(error.full_message).not_to include('fixture-password') }
+    [double(code: 302, to_s: 'fixture-secret'), double(code: 200, to_s: 'fixture-secret'),
+     double(code: 200, to_s: JSON.generate(envelope.merge('status' => false))),
+     double(code: 200, to_s: JSON.generate(envelope.merge('version' => '3.0')))].each do |response|
+      allow(RestClient::Request).to receive(:execute).and_return(response)
+      expect { fetch }.to raise_error(HaveAPI::Schema::Error) { |error| expect(error.full_message).not_to include('fixture-secret') }
+    end
+    expect(RestClient::Request).to have_received(:execute).exactly(5).times
+  end
+end

data/spec/schema_capture_wire.rb

@@ -0,0 +1,128 @@
+# Run after review with the prepared Ruby-client HTTP dependencies.
+require_relative '../lib/haveapi/schema'
+require 'socket'
+require 'timeout'
+require 'tmpdir'
+require 'stringio'
+require 'base64'
+
+def assert_capture(condition, message)
+  raise message unless condition
+end
+
+def serve_capture(socket, requests)
+  Timeout.timeout(2) do
+    method, path = socket.gets.to_s.split(' ', 3)
+    headers = {}
+    size = 0
+    while (line = socket.gets) && line != "\r\n"
+      size += line.bytesize
+      raise 'oversized fixture request' if size > 16_384
+
+      name, value = line.split(':', 2)
+      headers[name.downcase] = value.to_s.strip
+    end
+    requests << { method: method, path: path, headers: headers }
+    if path == '/redirect/v7.0/'
+      socket.write("HTTP/1.1 302 Found\r\nLocation: /redirect-target/v7.0/\r\nContent-Length: 0\r\nConnection: close\r\n\r\n")
+      return
+    end
+    unless %w[/v7.0/ /mounted/v7.0/ /bad-header/v7.0/].include?(path) && method == 'OPTIONS'
+      socket.write("HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n")
+      return
+    end
+
+    basic = "Basic #{Base64.strict_encode64('fixture-user:fixture-password')}"
+    authorized = headers['authorization'] == basic || headers['x-fixture-token'] == 'fixture-token'
+    resources = { 'public' => { 'actions' => {}, 'resources' => {} } }
+    resources['authorized'] = { 'actions' => {}, 'resources' => {} } if authorized
+    body = JSON.generate(
+      'status' => true, 'version' => '2.0', 'response' => {
+        'help' => path, 'meta' => { 'namespace' => '_meta' }, 'resources' => resources,
+        'authentication' => {
+          'token' => { 'http_header' => path.start_with?('/bad-header/') ? "X-Bad\r\nInjected" : 'X-Fixture-Token' }
+        }
+      }
+    )
+    socket.write("HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: #{body.bytesize}\r\nConnection: close\r\n\r\n#{body}")
+  end
+ensure
+  socket.close
+end
+
+server = TCPServer.new('127.0.0.1', 0)
+requests = []
+worker = Thread.new do
+  loop { serve_capture(server.accept, requests) }
+rescue IOError, Errno::EBADF
+  raise unless server.closed?
+end
+worker.report_on_exception = false
+previous = %w[HAVEAPI_CAPTURE_WIRE_PASSWORD HAVEAPI_CAPTURE_WIRE_TOKEN].to_h { |name| [name, ENV.fetch(name, nil)] }
+ENV['HAVEAPI_CAPTURE_WIRE_PASSWORD'] = 'fixture-password'
+ENV['HAVEAPI_CAPTURE_WIRE_TOKEN'] = 'fixture-token'
+
+begin
+  Timeout.timeout(20) do
+    Dir.mktmpdir('haveapi-schema-wire-') do |dir|
+      base = "http://127.0.0.1:#{server.addr[1]}"
+      ['', '/mounted'].each do |mount|
+        url = "#{base}#{mount}/v7.0/"
+        {
+          public: [],
+          basic: ['--basic-user', 'fixture-user', '--basic-password-env', 'HAVEAPI_CAPTURE_WIRE_PASSWORD'],
+          token: ['--token-env', 'HAVEAPI_CAPTURE_WIRE_TOKEN']
+        }.each do |mode, auth|
+          output = File.join(dir, 'schema.json')
+          File.write(output, 'previous snapshot')
+          out = StringIO.new
+          err = StringIO.new
+          first = requests.length
+          status = HaveAPI::Schema::FetchCommand.run(
+            [url, '--api-version', '7.0', '--profile', mode.to_s, '--output', output, *auth],
+            command_name: 'schema-wire', out: out, err: err
+          )
+          assert_capture(status == 0, "capture failed for #{mount}/#{mode}")
+          snapshot = HaveAPI::Schema::Snapshot.load(output)
+          assert_capture(snapshot['source_url'] == url && snapshot['mount_path'] == "#{mount}/", 'version or mount changed')
+          assert_capture(snapshot['description']['resources'].has_key?('authorized') == (mode != :public), 'wrong captured surface')
+          assert_capture(File.binread(output) == HaveAPI::Schema::Snapshot.canonical(snapshot).b, 'noncanonical saved bytes')
+          assert_capture(!File.read(output).include?('fixture-password') && !File.read(output).include?('fixture-token'), 'credential saved')
+          observed = requests.drop(first)
+          assert_capture(observed.length == (mode == :token ? 2 : 1), 'unexpected retry or auth action')
+          assert_capture(observed.all? { |r| r[:method] == 'OPTIONS' && r[:path] == "#{mount}/v7.0/" }, 'endpoint changed')
+          assert_capture(observed.all? { |r| r[:headers]['accept'].include?('json') }, 'JSON accept missing')
+          if mode == :token
+            assert_capture(!observed.first[:headers].has_key?('authorization') && !observed.first[:headers].has_key?('x-fixture-token'), 'discovery authenticated')
+            assert_capture(observed.last[:headers]['x-fixture-token'] == 'fixture-token', 'advertised header unused')
+          elsif mode == :basic
+            assert_capture(observed.first[:headers]['authorization'] == "Basic #{Base64.strict_encode64('fixture-user:fixture-password')}", 'Basic credentials missing')
+          end
+          assert_capture(out.string.empty? && err.string.empty?, 'unexpected command diagnostics')
+        end
+      end
+
+      %w[redirect bad-header].each do |failure|
+        output = File.join(dir, 'schema.json')
+        File.write(output, 'preserve on failure')
+        err = StringIO.new
+        first = requests.length
+        status = HaveAPI::Schema::FetchCommand.run(
+          ["#{base}/#{failure}/v7.0/", '--api-version', '7.0', '--profile', 'fixture',
+           '--output', output, '--token-env', 'HAVEAPI_CAPTURE_WIRE_TOKEN'],
+          command_name: 'schema-wire', out: StringIO.new, err: err
+        )
+        assert_capture(status == 1 && File.read(output) == 'preserve on failure', 'failed capture overwrote snapshot')
+        assert_capture(requests.length - first == 1, 'redirect followed or token sent after invalid discovery')
+        assert_capture(!err.string.include?('fixture-token') && !err.string.include?('Injected'), 'secret or header echoed')
+      end
+      assert_capture(Dir.children(dir) == ['schema.json'], 'temporary output leaked')
+    end
+    $stdout.puts 'Schema loopback: Public/Basic/existing-token root+mount capture, exact OPTIONS/header policy, redirects and atomic failure passed'
+  end
+ensure
+  previous.each { |name, value| value.nil? ? ENV.delete(name) : ENV[name] = value }
+  server.close
+  assert_capture(worker.join(2), 'fixture worker did not stop')
+  worker.value
+end

data/spec/schema_fetch_command_spec.rb

@@ -0,0 +1,102 @@
+require_relative 'schema_spec_helper'
+
+RSpec.describe HaveAPI::Schema::FetchCommand do
+  include SchemaFixtures
+
+  let(:out) { StringIO.new }
+  let(:err) { StringIO.new }
+
+  before do
+    allow(HaveAPI::Schema::Capture).to receive(:fetch).and_return(snapshot)
+  end
+
+  def run(output, *extra)
+    described_class.run([SchemaFixtures::URL, '--api-version', '7.0', '--profile', 'fixture',
+                         '--output', output, *extra], out: out, err: err, command_name: 'haveapi-example-client')
+  end
+
+  it 'writes canonical bytes atomically and leaves no temporary files' do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, 'schema.json')
+      File.write(path, 'old')
+      expect(run(path)).to eq(0)
+      expect(File.binread(path)).to eq(HaveAPI::Schema::Snapshot.canonical(snapshot))
+      expect(Dir.children(dir)).to eq(['schema.json'])
+      expect(HaveAPI::Schema::Capture).to have_received(:fetch).with(
+        url: SchemaFixtures::URL, api_version: '7.0', profile: 'fixture',
+        basic_user: nil, basic_password: nil, token: nil, diagnostics: []
+      )
+    end
+  end
+
+  it 'resolves Basic and existing-token credentials only through named environment variables' do
+    stub_const('ENV', ENV.to_h.merge('SCHEMA_TEST_PASSWORD' => 'fixture-password', 'SCHEMA_TEST_TOKEN' => 'fixture-token'))
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, 'schema.json')
+      expect(run(path, '--basic-user', 'user', '--basic-password-env', 'SCHEMA_TEST_PASSWORD')).to eq(0)
+      expect(HaveAPI::Schema::Capture).to have_received(:fetch).with(hash_including(basic_user: 'user', basic_password: 'fixture-password'))
+      expect(run(path, '--token-env', 'SCHEMA_TEST_TOKEN')).to eq(0)
+      expect(HaveAPI::Schema::Capture).to have_received(:fetch).with(hash_including(token: 'fixture-token'))
+      expect(out.string + err.string + File.read(path)).not_to include('fixture-password', 'fixture-token')
+    end
+  end
+
+  it 'rejects invalid credential options before network or output mutation without echoing raw arguments' do
+    stub_const('ENV', ENV.to_h.merge('SCHEMA_EMPTY' => '', 'SCHEMA_BAD' => "fixture-secret\n"))
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, 'schema.json')
+      File.write(path, 'old')
+      [
+        ['--basic-user', 'user'], ['--basic-password-env', 'MISSING'], ['--token-env', 'MISSING'],
+        ['--token-env', 'SCHEMA_EMPTY'], ['--token-env', 'SCHEMA_BAD'], ['--token-env', 'bad=name'],
+        ['--token-env', 'SCHEMA_EMPTY', '--basic-user', 'user', '--basic-password-env', 'SCHEMA_BAD'],
+        ['--basic-password', 'fixture-secret'], ['--unknown=fixture-secret']
+      ].each do |args|
+        expect(run(path, *args)).to eq(1)
+        expect(File.read(path)).to eq('old')
+        expect(Dir.children(dir)).to eq(['schema.json'])
+      end
+      expect(HaveAPI::Schema::Capture).not_to have_received(:fetch)
+      expect(err.string).not_to include('fixture-secret')
+    end
+  end
+
+  it 'preserves old output on capture, validation and atomic-save failures' do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, 'schema.json')
+      File.write(path, 'old')
+      allow(HaveAPI::Schema::Capture).to receive(:fetch).and_raise(HaveAPI::Schema::Error, 'capture failed')
+      expect(run(path)).to eq(1)
+      expect(File.read(path)).to eq('old')
+      allow(HaveAPI::Schema::Capture).to receive(:fetch).and_return(snapshot.merge('protocol_version' => '3.0'))
+      expect(run(path)).to eq(1)
+      expect(File.read(path)).to eq('old')
+      allow(HaveAPI::Schema::Capture).to receive(:fetch).and_return(snapshot)
+      allow(File).to receive(:rename).and_raise(Errno::EACCES, 'fixture-secret')
+      expect(run(path)).to eq(1)
+      expect(File.read(path)).to eq('old')
+      expect(Dir.children(dir)).to eq(['schema.json'])
+      expect(err.string).not_to include('fixture-secret')
+    end
+  end
+
+  it 'refuses a symlink destination or missing parent before acquisition' do
+    Dir.mktmpdir do |dir|
+      target = File.join(dir, 'target')
+      File.write(target, 'keep')
+      path = File.join(dir, 'schema.json')
+      File.symlink(target, path)
+      expect(run(path)).to eq(1)
+      expect(File.read(target)).to eq('keep')
+      expect(run(File.join(dir, 'missing/schema.json'))).to eq(1)
+      expect(Dir.children(dir).sort).to eq(%w[schema.json target])
+      expect(HaveAPI::Schema::Capture).not_to have_received(:fetch)
+    end
+  end
+
+  it 'returns help without loading capture dependencies or creating output' do
+    expect(described_class.run(['--help'], out: out, err: err, command_name: 'haveapi-example-client')).to eq(0)
+    expect(out.string).to include('fetch URL', '--api-version', '--basic-password-env', '--token-env')
+    expect(HaveAPI::Schema::Capture).not_to have_received(:fetch)
+  end
+end

data/spec/schema_snapshot_spec.rb

@@ -0,0 +1,122 @@
+require_relative 'schema_spec_helper'
+
+RSpec.describe HaveAPI::Schema::Snapshot do
+  include SchemaFixtures
+
+  it 'loads offline without the dynamic client, transport or a bundle' do
+    script = <<~RUBY
+      require 'haveapi/schema'
+      abort 'dynamic client loaded' if defined?(RestClient) || defined?(HaveAPI::Client::Client)
+      identity = HaveAPI::Schema.source_identity
+      abort 'mutable identity' unless identity.frozen? && identity.values.all?(&:frozen?)
+      puts identity.fetch('package_name')
+      puts identity.fetch('version')
+    RUBY
+    lib = File.expand_path('../lib', __dir__)
+    out, err, status = Open3.capture3({ 'RUBYOPT' => nil, 'RUBYLIB' => nil }, RbConfig.ruby, '--disable-gems', '-I', lib, '-e', script)
+    expect(status.success?).to be(true), err
+    expect(out.lines.map(&:strip)).to eq(['haveapi-client', HaveAPI::Client::VERSION])
+  end
+
+  it 'uses the established canonical bytes and preserves array order and UTF-8 data' do
+    expected = <<~JSON
+      {
+        "a": "č",
+        "z": [
+          {
+            "a": 2,
+            "b": 1
+          },
+          0
+        ]
+      }
+    JSON
+    expect(described_class.canonical('z' => [{ 'b' => 1, 'a' => 2 }, 0], 'a' => 'č')).to eq(expected)
+    expect(described_class.sha256(snapshot)).to eq(Digest::SHA256.hexdigest(described_class.canonical(snapshot)))
+  end
+
+  it 'matches a mounted format 1 snapshot without rewriting saved data' do
+    expected = {
+      'schema_format' => 1, 'api_version' => '7.0', 'protocol_version' => '2.0',
+      'source_url' => SchemaFixtures::URL, 'profile' => 'fixture', 'mount_path' => '/mount/', 'description' => description
+    }
+    expect(snapshot).to eq(expected)
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, 'schema.json')
+      bytes = described_class.canonical(expected)
+      File.write(path, bytes)
+      expect(described_class.load(path)).to eq(expected)
+      expect(File.binread(path)).to eq(bytes)
+    end
+  end
+
+  it 'preserves Custom/default and choice keys while stripping prose and protected defaults' do
+    diagnostics = []
+    data = { 'help' => '/data?token=data', 'fetch_url' => 'custom:value', 'description' => 'data' }
+    source = { 'parameters' => {
+      'description' => { 'type' => 'Custom', 'default' => data, 'description' => 'prose' },
+      'secret' => { 'protected' => true, 'default' => 'fixture-secret' },
+      'choice' => { 'validators' => { 'include' => { 'values' => { 'help' => 'label' }, 'message' => 'private' } } }
+    } }
+    cleaned = described_class.sanitize(source, diagnostics: diagnostics)
+    expect(cleaned.dig('parameters', 'description')).to eq('type' => 'Custom', 'default' => data)
+    expect(cleaned.dig('parameters', 'secret')).not_to have_key('default')
+    expect(cleaned.dig('parameters', 'choice', 'validators', 'include')).to eq('values' => { 'help' => nil })
+    expect(diagnostics).to eq(['removed protected default: parameters/secret'])
+  end
+
+  it 'rejects nested structural endpoints during capture and load without echoing their values' do
+    %w[help path choices_path choices_url].each do |key|
+      value = key.end_with?('_url') ? 'https://user:fixture-secret@example.test/' : '/mount/v7.0/?token=fixture-secret'
+      schema = snapshot
+      schema['description']['resources']['widget']['choices'] = { key => value }
+      [-> { described_class.validate(schema) },
+       lambda {
+         described_class.from_envelope(envelope.merge('response' => schema['description']), api_version: '7.0',
+                                                                                            source_url: SchemaFixtures::URL, profile: 'fixture', mount_path: '/mount/')
+       }].each do |operation|
+        expect(&operation).to raise_error(HaveAPI::Schema::Error) do |error|
+          expect(error.message).to include("resources/widget/choices/#{key}")
+          expect(error.message).not_to include('fixture-secret', value)
+        end
+      end
+    end
+  end
+
+  it 'rejects malformed envelopes, unsafe paths, mismatched versions and protocols' do
+    [nil, {}, { 'status' => false }, { 'status' => true }].each do |value|
+      expect { described_class.from_envelope(value, api_version: '7.0', source_url: SchemaFixtures::URL, profile: 'fixture') }
+        .to raise_error(HaveAPI::Schema::Error)
+    end
+    %w[/../ /%2e%2e/ /%2f/ /bad%/ //evil/].each { |path| expect(described_class.safe_path?(path)).to be(false) }
+    expect { described_class.validate(snapshot.merge('protocol_version' => '3.0')) }.to raise_error(HaveAPI::Schema::Error)
+    expect { described_class.validate(snapshot.merge('api_version' => '8.0')) }.to raise_error(HaveAPI::Schema::Error)
+    expect { described_class.endpoint!('https://user:secret@example.test/v7.0/') }.to raise_error(HaveAPI::Schema::Error)
+  end
+
+  it 'binds source identity to the actual version and all five shared logical source files' do
+    lib = File.expand_path('../lib', __dir__)
+    paths = %w[haveapi/schema.rb haveapi/schema/snapshot.rb haveapi/schema/capture.rb
+               haveapi/schema/fetch_command.rb haveapi/client/version.rb].sort
+    digest = Digest::SHA256.new
+    paths.each { |path| digest.update(path).update("\0").update(File.binread(File.join(lib, path))).update("\0") }
+    expect(HaveAPI::Schema.source_identity).to eq(
+      'package_name' => 'haveapi-client', 'version' => HaveAPI::Client::VERSION, 'source_sha256' => digest.hexdigest
+    )
+  end
+
+  it 'keeps relative owned-file segments compatible without relaxing absolute endpoint paths' do
+    expect(described_class.safe_segments?('resources/widget/show.rs')).to be(true)
+    expect(described_class.safe_segments?('/mount/v7.0/')).to be(true)
+    ['../outside.rs', 'resources/./show.rs', 'resources/%2e%2e/show.rs', 'resources/%2f/show.rs',
+     'resources/%5c/show.rs', 'resources/bad%/show.rs', 'resources/with space.rs', "resources/\nshow.rs",
+     'resources/show.rs?token=data', 'resources/show.rs#fragment', '//outside', nil].each do |path|
+      expect(described_class.safe_segments?(path)).to be(false)
+    end
+    expect(described_class.safe_path?('resources/widget/show.rs')).to be(false)
+    expect { described_class.endpoint!('https://schema.example.test/mount/%2e%2e/v7.0/') }
+      .to raise_error(HaveAPI::Schema::Error)
+    expect { described_class.validate_machine_endpoint('path', 'resources/widget/show.rs') }
+      .to raise_error(HaveAPI::Schema::Error)
+  end
+end

data/spec/schema_spec_helper.rb

@@ -0,0 +1,27 @@
+require_relative '../lib/haveapi/schema'
+require 'tmpdir'
+require 'stringio'
+require 'open3'
+require 'rbconfig'
+
+module SchemaFixtures
+  URL = 'https://schema.example.test/mount/v7.0/'.freeze
+
+  def description
+    {
+      'help' => '/mount/v7.0/', 'meta' => { 'namespace' => '_meta' },
+      'authentication' => {}, 'resources' => {
+        'widget' => { 'actions' => {}, 'resources' => {} }
+      }
+    }
+  end
+
+  def envelope
+    { 'status' => true, 'version' => '2.0', 'response' => description }
+  end
+
+  def snapshot
+    HaveAPI::Schema::Snapshot.from_envelope(envelope, api_version: '7.0', source_url: URL,
+                                                      profile: 'fixture', mount_path: '/mount/')
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi-client
 version: !ruby/object:Gem::Version
-  version: 0.30.2
+  version: 0.31.0
 platform: ruby
 authors:
 - Jakub Skokan
@@ -152,6 +152,10 @@ files:
 - lib/haveapi/client/validators/numericality.rb
 - lib/haveapi/client/validators/presence.rb
 - lib/haveapi/client/version.rb
+- lib/haveapi/schema.rb
+- lib/haveapi/schema/capture.rb
+- lib/haveapi/schema/fetch_command.rb
+- lib/haveapi/schema/snapshot.rb
 - lib/restclient_ext/resource.rb
 - spec/action_security_spec.rb
 - spec/authentication_token_security_spec.rb
@@ -163,6 +167,11 @@ files:
 - spec/integration/typed_input_spec.rb
 - spec/load_spec.rb
 - spec/resource_instance_association_spec.rb
+- spec/schema_capture_spec.rb
+- spec/schema_capture_wire.rb
+- spec/schema_fetch_command_spec.rb
+- spec/schema_snapshot_spec.rb
+- spec/schema_spec_helper.rb
 - spec/spec_helper.rb
 - spec/support/test_server.rb
 - spec/validators/inclusion_spec.rb