thuban 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e52056d963a0a6c8bb0ef6efa4b99a5a3dcae5e77f098dda27fd3b3805a4e224
-  data.tar.gz: 8beb8fdd5713ea96004344de2bc6973a09ead85772596de17d76988cd0064589
+  metadata.gz: 7115dc5cf395114ca07172c0746db9d0efb228092455b2a0fc7ec069a01b7e7a
+  data.tar.gz: 5ed48fad9aab26581024ca4c96100e53f2072fdab5727acb37cad4ce5b34872c
 SHA512:
-  metadata.gz: 8014b9b58cdc918c361461ef5100adbdd02243a710587857e0bf9fa7d9c4c23eacfdd04c0bbb96fb251172b2d432754fa35ae363ac13e664562efe360c5b60f1
-  data.tar.gz: efcf26c58b99c870914943fddec1a1b347eb0b40ab29b1074e65fb4074f64f3aae5d464b15a71f78ac2ed3e0a8eeedde4832c2bc32ae2e208df77a60bd5d7758
+  metadata.gz: ab9dd86e88c0cf633d21a6489879415ca329146a7aa6aace8eac91b11280e6fe759ce7c11a453a96f8e409b35d0ddb2530b05f6dc8fa8225c7ce5c3f71a6dfab
+  data.tar.gz: e99576b1552149f56fe50b6730743d5afe6efa475b6879e2146ffef81cc106eaa94eb1d907ab3fac53248bbc92c3e32a1aab46783073b6307e2888d68acebf4a

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+## 0.4.0 - 2026-09-15
+
+- Add pkt-line parsing and smart HTTP protocol v2/v0 reference discovery
+- Add smart HTTP fetch negotiation and bounded pack ingestion
+- Add configured repository remotes and remote-tracking ref updates
+- Add redacted Basic, Bearer, callback, and Git credential-helper authentication
+- Add bounded SSH ref discovery and fetch through the system SSH client
+- Add local, smart HTTP, and SSH push with refspecs, leases, atomic updates, and progress
+- Add fetch progress, shallow depth negotiation, and `blob:none` partial fetches
+
 ## 0.3.0 - 2026-09-15
 
 - Add loose object, tree, and commit writing

data/README.md

@@ -1,7 +1,7 @@
 <h1 align="center">Thuban</h1>
 
 <p align="center">
-  <strong>A pure Ruby implementation for local Git repositories</strong>
+  <strong>A pure Ruby Git implementation for local repositories and remote transfers</strong>
 </p>
 
 <p align="center">
@@ -23,8 +23,8 @@
 ---
 
 Thuban is a pure Ruby Git implementation for reading and writing local
-repositories. It works directly with repository data without invoking the Git
-executable.
+repositories and transferring data with local, smart HTTP, or SSH remotes. Local
+repository operations work directly with Git data without invoking the Git executable.
 
 ## Features
 
@@ -34,6 +34,11 @@ executable.
 - Writes loose objects, index entries, refs, reflogs, trees, and commits
 - Finds merge bases and performs reset, cherry-pick, revert, and stash operations
 - Writes interoperable delta-free Git packfiles to any writable IO
+- Discovers smart HTTP protocol v2 and v0 remote references
+- Fetches smart HTTP packs into the local object database
+- Authenticates smart HTTP with Basic, Bearer, callbacks, or Git credential helpers
+- Pushes refs and packfiles with force-with-lease and atomic update support
+- Discovers, fetches, and pushes SSH remotes through the system `ssh` executable
 - Tracks line history across commits and renames with blame
 - Writes files atomically and checks out branches with collision guards
 - Supports linked worktrees and packed refs
@@ -43,7 +48,7 @@ executable.
 Add Thuban to your Gemfile:
 
 ```ruby
-gem "thuban", "~> 0.2.0"
+gem "thuban", "~> 0.3.0"
 ```
 
 Then install it:
@@ -194,6 +199,141 @@ end
 
 The emitted PACK v2 stream stores complete compressed objects without delta
 generation. It can be consumed by `git index-pack` and `git verify-pack`.
+`Thuban::Pack.read_stream(io, repo.odb)` verifies and expands a received pack,
+including offset and reference deltas, into the supplied object database.
+
+### Inspect Remote References
+
+Smart HTTP discovery prefers protocol v2 and falls back to v0 when necessary:
+
+```ruby
+connection = Thuban::Remote.open("https://example.com/project.git")
+begin
+  connection.refs.each do |ref|
+    puts [ref.oid, ref.name, ref.symref_target, ref.peeled].compact.join(" ")
+  end
+ensure
+  connection.close
+end
+```
+
+Fetch selected object IDs directly, optionally providing local object IDs for
+negotiation:
+
+```ruby
+wanted = connection.refs.find { |ref| ref.name == "refs/heads/main" }.oid
+received_oids = connection.fetch(repo, wants: [wanted], haves: repo.refs.values.compact)
+```
+
+Authenticate with fixed Basic or Bearer credentials when appropriate:
+
+```ruby
+credentials = Thuban::Remote::Credentials.static(
+  username: ENV.fetch("GIT_USERNAME"),
+  password: ENV.fetch("GIT_PASSWORD")
+)
+connection = Thuban::Remote.open(remote_url, credentials: credentials)
+
+token = Thuban::Remote::Credentials.bearer(token: ENV.fetch("GIT_TOKEN"))
+connection = Thuban::Remote.open(remote_url, credentials: token)
+```
+
+For credentials that are selected or refreshed at runtime, return another
+credential object from a callback. The callback receives the remote URL with no
+embedded user information:
+
+```ruby
+credentials = Thuban::Remote::Credentials.callback do |url|
+  Thuban::Remote::Credentials.bearer(token: token_for(url))
+end
+```
+
+Use the normal configured Git credential helpers, or select a helper by name:
+
+```ruby
+credentials = Thuban::Remote::Credentials.helper
+credentials = Thuban::Remote::Credentials.helper("store --file=/secure/path")
+connection = Thuban::Remote.open(remote_url, credentials: credentials)
+```
+
+Helper lookup uses `git credential fill` with terminal prompting disabled and is
+bounded by the connection timeout. Thuban never includes credentials, helper
+output, response bodies, or remote URLs in transport errors. Credential objects
+also redact their inspection output. URL-embedded credentials and HTTP redirects
+remain rejected so an authorization header cannot be forwarded to another
+origin.
+
+For a repository with a normal `[remote "origin"]` configuration, the
+high-level operation reads its fetch refspec and updates remote-tracking refs:
+
+```ruby
+repo.remotes # => {"origin" => "https://example.com/project.git"}
+remote_refs = repo.fetch("origin")
+```
+
+Limit downloaded history or omit blobs while reporting bounded transfer and pack
+progress:
+
+```ruby
+repo.fetch("origin", depth: 1) { |event| warn "#{event.phase}: #{event.bytes}" }
+repo.fetch("origin", filter: "blob:none")
+```
+
+`depth:` accepts positive 32-bit integers and `filter:` currently accepts only
+`"blob:none"`. Thuban negotiates only features advertised by the server. Shallow
+boundaries are atomically maintained in Git's `shallow` file. For configured
+remotes, partial fetches also set Git's `remote.<name>.promisor` and
+`remote.<name>.partialclonefilter` keys, so the Git executable can retrieve an
+omitted object later. Reading an omitted blob through Thuban raises `KeyError`;
+automatic promisor-object retrieval remains the caller's responsibility.
+Progress `bytes` are cumulative for `:pack` events and the current sideband
+message size for `:remote` events, matching push progress.
+
+Push one or more explicit refspecs. Normal updates must be fast-forward; use a
+lease for a guarded rewrite, or `force: true` for an unconditional one:
+
+```ruby
+repo.push("origin", refspecs: "refs/heads/main:refs/heads/main")
+repo.push("origin", refspecs: "refs/heads/topic:refs/heads/topic",
+  lease: expected_remote_oid)
+repo.push("origin", refspecs: [
+  "refs/heads/main:refs/heads/main",
+  "refs/tags/v1:refs/tags/v1"
+], atomic: true) { |progress| warn "#{progress.phase}: #{progress.current}/#{progress.total}" }
+```
+
+Remote names, direct paths, `file://` URLs, HTTP(S), and SSH URLs are accepted.
+At the lower level, `Connection#push` accepts `[ref, old_oid, new_oid]` updates;
+the old object ID is an optimistic lease, and `nil` uses the advertised value.
+Deletion uses an empty source refspec such as `:refs/heads/topic`.
+
+Fetched packs are checksum-verified, bounded by byte/object/expanded-size
+limits, and expanded through the existing object database. Redirects and
+URL-embedded credentials remain rejected.
+
+SSH remotes accept both standard URL and scp-like forms. Thuban invokes the
+system SSH client without a local shell and uses `git-upload-pack` or
+`git-receive-pack` over its
+standard input and output:
+
+```ruby
+connection = Thuban::Remote.open("ssh://git@example.com/project.git")
+connection = Thuban::Remote.open("git@example.com:project.git")
+```
+
+Pass `ssh:` as an argument array or safely parsed command string to select a
+client and options. When omitted, `GIT_SSH_COMMAND` is parsed into arguments, or
+`ssh` is used by default:
+
+```ruby
+connection = Thuban::Remote.open(remote_url, ssh: ["ssh", "-F", "/safe/config"])
+```
+
+SSH runs in batch mode, is bounded by `timeout:`, and discards stderr so remote
+paths and server diagnostics are not copied into exceptions. User, host, port,
+and path syntax is validated before process startup. Passwords in SSH URLs are
+not supported; use normal SSH agents and configuration instead. SSH fetches use
+the same shallow, partial, sideband progress, and pack validation paths as HTTP.
 
 ### Match Ignored Paths
 
@@ -216,9 +356,11 @@ continuations, and command-scoped overrides are not evaluated.
 
 The current write API covers loose objects, the index, refs, reflogs, commits,
 guarded checkout, local history operations, stash, and delta-free pack output.
-Thuban does not yet perform network operations, merges, pack delta generation,
-or streaming pack ingestion. It does not provide its own diff algorithm; blame
-delegates line matching to Porrima through the injectable `differ:` argument.
+Thuban can fetch and push local, smart HTTP, and SSH remotes, including shallow
+and blobless fetches. Merges, automatic retrieval of omitted promisor objects,
+and pack delta generation are outside the current scope. It does not provide
+its own diff algorithm; blame delegates line matching to Porrima through the
+injectable `differ:` argument.
 
 Support is limited to the index and pack formats covered by the test suite.
 Submodule checkout and optional Git extensions outside that coverage are not
@@ -233,6 +375,7 @@ ruby tools/check_isolation.rb
 bundle exec rbs -I sig -r porrima validate
 gem build --strict thuban.gemspec
 ruby bench/pack_write.rb --assert
+ruby bench/ssh_fetch.rb --assert
 ```
 
 ## Contributing

data/lib/thuban/pack_reader.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Thuban
+  class Pack
+    MAX_PACK_SIZE = 1024 * 1024 * 1024
+    MAX_PACK_OBJECTS = 1_000_000
+    MAX_DEFERRED_DELTA_BYTES = 128 * 1024 * 1024
+    MAX_EXPANDED_PACK_SIZE = 4 * 1024 * 1024 * 1024
+
+    def self.read_stream(io, odb)
+      raise TypeError, "pack input must respond to read" unless io.respond_to?(:read)
+      raise TypeError, "expected Thuban::ObjectDatabase" unless odb.is_a?(ObjectDatabase)
+
+      Tempfile.create(["thuban-pack-", ".pack"]) do |file|
+        file.binmode
+        copy_stream(io, file, MAX_PACK_SIZE)
+        file.flush
+        unpack_file(file, odb) { |current, total| yield current, total if block_given? }
+      end
+    end
+
+    def self.copy_stream(input, output, limit)
+      total = 0
+      loop do
+        chunk = input.read(65_536)
+        break if chunk.nil?
+        raise CorruptObject, "pack input stopped before EOF" unless chunk.is_a?(String) && !chunk.empty?
+
+        total += chunk.bytesize
+        raise CorruptObject, "pack exceeds size limit" if total > limit
+
+        output.write(chunk)
+      end
+      total
+    end
+    private_class_method :copy_stream
+
+    def self.unpack_file(file, odb)
+      size = file.size
+      raise CorruptObject, "truncated pack" if size < 32
+      pack_end = size - 20
+      verify_pack_checksum(file, pack_end)
+      file.rewind
+      header = file.read(12)
+      valid = header.start_with?("PACK") && [2, 3].include?(header[4, 4].unpack1("N"))
+      raise CorruptObject, "invalid pack header" unless valid
+
+      count = header[8, 4].unpack1("N")
+      raise CorruptObject, "pack object count exceeds limit" if count > MAX_PACK_OBJECTS
+      resolved = {}
+      deferred = []
+      deferred_bytes = 0
+      expanded_bytes = 0
+      oids = []
+      count.times do
+        record = read_record(file, pack_end)
+        object = resolve_record(record, resolved, odb, MAX_EXPANDED_PACK_SIZE - expanded_bytes)
+        if object
+          oid, object_size = object
+          resolved[record[:offset]] = oid
+          oids << oid
+          expanded_bytes += object_size
+          yield oids.length, count if block_given?
+        else
+          deferred << record
+          deferred_bytes += record[:data].bytesize
+          raise CorruptObject, "deferred deltas exceed memory limit" if deferred_bytes > MAX_DEFERRED_DELTA_BYTES
+        end
+      end
+      raise CorruptObject, "pack object count mismatch" unless file.pos == pack_end
+
+      waiting_by_offset = Hash.new { |hash, key| hash[key] = [] }
+      waiting_by_oid = Hash.new { |hash, key| hash[key] = [] }
+      deferred.each do |record|
+        target = record[:base_oid] ? waiting_by_oid[record[:base_oid]] : waiting_by_offset[record[:base_offset]]
+        target << record
+      end
+      deferred.clear
+      queue = []
+      resolved.each do |offset, oid|
+        queue.concat(waiting_by_offset.delete(offset) || [])
+        queue.concat(waiting_by_oid.delete(oid) || [])
+      end
+      waiting_by_oid.keys.each do |oid|
+        queue.concat(waiting_by_oid.delete(oid)) if odb.exist?(oid)
+      end
+      cursor = 0
+      while cursor < queue.length
+        record = queue[cursor]
+        cursor += 1
+        object = resolve_record(record, resolved, odb, MAX_EXPANDED_PACK_SIZE - expanded_bytes)
+        raise CorruptObject, "unresolved delta base" unless object
+
+        oid, object_size = object
+        resolved[record[:offset]] = oid
+        oids << oid
+        expanded_bytes += object_size
+        yield oids.length, count if block_given?
+        queue.concat(waiting_by_offset.delete(record[:offset]) || [])
+        queue.concat(waiting_by_oid.delete(oid) || [])
+      end
+      raise CorruptObject, "unresolved delta base" unless waiting_by_offset.empty? && waiting_by_oid.empty?
+
+      oids
+    end
+    private_class_method :unpack_file
+
+    def self.verify_pack_checksum(file, pack_end)
+      digest = Digest::SHA1.new
+      file.rewind
+      remaining = pack_end
+      while remaining.positive?
+        chunk = file.read([remaining, 65_536].min)
+        raise CorruptObject, "truncated pack" unless chunk&.bytesize&.positive?
+
+        digest.update(chunk)
+        remaining -= chunk.bytesize
+      end
+      expected = file.read(20)
+      raise CorruptObject, "pack checksum mismatch" unless expected&.bytesize == 20 && digest.digest == expected
+    end
+    private_class_method :verify_pack_checksum
+
+    def self.read_record(file, pack_end)
+      offset = file.pos
+      byte = file.getbyte
+      raise CorruptObject, "truncated pack object" unless byte
+
+      type = (byte >> 4) & 7
+      size = byte & 15
+      shift = 4
+      while (byte & 0x80).positive?
+        byte = file.getbyte
+        raise CorruptObject, "truncated pack object size" unless byte && shift <= 63
+
+        size |= (byte & 0x7f) << shift
+        shift += 7
+      end
+      raise CorruptObject, "pack object too large" if size > MAX_OBJECT_SIZE
+
+      record = {offset: offset, type: TYPES[type]}
+      if type == 6
+        record[:base_offset] = offset - read_delta_distance(file)
+        raise CorruptObject, "invalid delta base offset" unless record[:base_offset] >= 12 && record[:base_offset] < offset
+      elsif type == 7
+        base = file.read(20)
+        raise CorruptObject, "truncated delta reference" unless base&.bytesize == 20
+
+        record[:base_oid] = base.unpack1("H*")
+      elsif !record[:type]
+        raise CorruptObject, "invalid packed object type #{type}"
+      end
+      record[:data] = inflate_record(file, size, pack_end)
+      record
+    end
+    private_class_method :read_record
+
+    def self.read_delta_distance(file)
+      byte = file.getbyte
+      raise CorruptObject, "truncated delta offset" unless byte
+
+      distance = byte & 0x7f
+      count = 0
+      while (byte & 0x80).positive?
+        byte = file.getbyte
+        count += 1
+        raise CorruptObject, "invalid delta offset" unless byte && count <= 9
+
+        distance = ((distance + 1) << 7) | (byte & 0x7f)
+      end
+      distance
+    end
+    private_class_method :read_delta_distance
+
+    def self.inflate_record(file, size, pack_end)
+      inflater = Zlib::Inflate.new
+      data = +"".b
+      start = file.pos
+      until inflater.finished?
+        remaining = pack_end - file.pos
+        raise CorruptObject, "truncated compressed object" unless remaining.positive?
+
+        chunk = file.read([remaining, 16_384].min)
+        inflater.inflate(chunk) do |part|
+          data << part
+          raise CorruptObject, "packed object exceeds declared size" if data.bytesize > size
+        end
+      end
+      file.seek(start + inflater.total_in, IO::SEEK_SET)
+      raise CorruptObject, "packed object size mismatch" unless data.bytesize == size
+
+      data
+    rescue Zlib::Error => error
+      raise CorruptObject, error.message
+    ensure
+      inflater&.close
+    end
+    private_class_method :inflate_record
+
+    def self.resolve_record(record, resolved, odb, remaining)
+      type = record[:type]
+      data = record[:data]
+      unless type
+        base_oid = record[:base_oid] || resolved[record[:base_offset]]
+        return unless base_oid && odb.exist?(base_oid)
+
+        type, base = odb.read(base_oid)
+        data = apply_delta(base, data)
+      end
+      raise CorruptObject, "expanded pack exceeds size limit" if data.bytesize > remaining
+
+      [odb.write(type, data), data.bytesize]
+    end
+    private_class_method :resolve_record
+  end
+end

data/lib/thuban/remote/credentials.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Thuban
+  module Remote
+    module Credentials
+      MAX_HELPER_OUTPUT = 1024 * 1024
+
+      class Provider
+        def inspect = "#<#{self.class.name} [REDACTED]>"
+      end
+      class Basic < Provider
+        def initialize(username, password)
+          @username = username
+          @password = password
+        end
+
+        def authorization(_url, timeout:)
+          "Basic #{["#{@username}:#{@password}"].pack("m0")}"
+        end
+      end
+      class Bearer < Provider
+        def initialize(token) = @token = token
+        def authorization(_url, timeout:) = "Bearer #{@token}"
+      end
+      class Callback < Provider
+        def initialize(callback) = @callback = callback
+
+        def authorization(url, timeout:)
+          credential = @callback.call(url.to_s.freeze)
+          return if credential.nil?
+          raise AuthenticationError, "credential callback returned an invalid value", cause: nil unless credential.is_a?(Provider)
+          raise AuthenticationError, "credential callback cannot return itself", cause: nil if credential.equal?(self)
+
+          credential.authorization(url, timeout: timeout)
+        rescue AuthenticationError
+          raise
+        rescue StandardError
+          raise AuthenticationError, "credential callback failed", cause: nil
+        end
+      end
+
+      class Helper < Provider
+        def initialize(name) = @name = name
+
+        def authorization(url, timeout:)
+          fields = parse(run(input_for(url), timeout))
+          if fields["username"] && fields.key?("password")
+            return Credentials.static(username: fields["username"], password: fields["password"]).authorization(url, timeout: timeout)
+          end
+          if fields["authtype"]&.casecmp?("Bearer") && fields["credential"]
+            return Credentials.bearer(token: fields["credential"]).authorization(url, timeout: timeout)
+          end
+
+          raise AuthenticationError, "credential helper returned no usable credentials", cause: nil
+        rescue ArgumentError
+          raise AuthenticationError, "credential helper returned invalid credentials", cause: nil
+        end
+
+        private
+
+        def command
+          return ["git", "credential", "fill"] unless @name
+
+          ["git", "-c", "credential.helper=", "-c", "credential.helper=#{@name}", "credential", "fill"]
+        end
+
+        def input_for(url)
+          host = url.hostname
+          host = "[#{host}]" if host.include?(":")
+          host = "#{host}:#{url.port}" unless url.port == url.default_port
+          "capability[]=authtype\nprotocol=#{url.scheme}\nhost=#{host}\npath=#{url.path.delete_prefix("/")}\n\n"
+        end
+
+        def run(input, timeout)
+          grouped = !Gem.win_platform?
+          options = grouped ? {pgroup: true} : {}
+          stdin, stdout, stderr, waiter = Open3.popen3(helper_environment, *command, **options)
+          errors = Thread.new { while stderr.read(4096); end rescue nil }
+          output_error = nil
+          output = Thread.new do
+            read_bounded(stdout)
+          rescue AuthenticationError => error
+            output_error = error
+            nil
+          rescue StandardError
+            output_error = AuthenticationError.new("credential helper failed")
+            nil
+          end
+          stdin.write(input)
+          stdin.close
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          while waiter.alive? || output.alive?
+            raise output_error if output_error
+
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise AuthenticationError, "credential helper timed out", cause: nil unless remaining.positive?
+
+            (waiter.alive? ? waiter : output).join([remaining, 0.01].min)
+          end
+          raise output_error if output_error
+          raise AuthenticationError, "credential helper failed", cause: nil unless waiter.value.success?
+
+          output.value
+        rescue AuthenticationError
+          raise
+        rescue StandardError
+          raise AuthenticationError, "credential helper failed", cause: nil
+        ensure
+          terminate(waiter, grouped) if waiter&.alive?
+          [stdin, stdout, stderr].compact.each { |io| io.close unless io.closed? }
+          output&.join
+          errors&.join
+        end
+
+        def read_bounded(io)
+          result = +"".b
+          while (chunk = io.read(4096))
+            result << chunk
+            raise AuthenticationError, "credential helper output exceeds size limit", cause: nil if result.bytesize > MAX_HELPER_OUTPUT
+          end
+          result
+        end
+
+        def terminate(waiter, grouped)
+          unless grouped
+            Process.kill("KILL", waiter.pid)
+            waiter.join
+            return
+          end
+
+          target = -waiter.pid
+          Process.kill("TERM", target)
+          return if waiter.join(0.2)
+
+          Process.kill("KILL", target)
+          waiter.join
+        rescue SystemCallError
+          nil
+        end
+
+        def helper_environment
+          {"GIT_TERMINAL_PROMPT" => "0", "GCM_INTERACTIVE" => "Never",
+           "GIT_TRACE" => nil, "GIT_TRACE2" => nil, "GIT_TRACE_CURL" => nil}
+        end
+
+        def parse(output)
+          fields = {}
+          output.b.each_line(chomp: true) do |line|
+            line = line.delete_suffix("\r")
+            break if line.empty?
+
+            key, value = line.split("=", 2)
+            raise AuthenticationError, "credential helper returned invalid output", cause: nil unless value && /\A[a-zA-Z0-9_-]+(?:\[\])?\z/n.match?(key)
+
+            if key.end_with?("[]")
+              (fields[key] ||= []) << value
+              next
+            end
+            raise AuthenticationError, "credential helper returned duplicate fields", cause: nil if fields.key?(key)
+
+            fields[key] = value
+          end
+          fields
+        end
+      end
+
+      def self.static(username:, password:)
+        validate_basic(username, password)
+        Basic.new(username.dup.freeze, password.dup.freeze)
+      end
+
+      def self.bearer(token:)
+        raise ArgumentError, "bearer token must be a non-empty String without whitespace" unless token.is_a?(String) && /\A[^\x00-\x20\x7f]+\z/n.match?(token)
+
+        Bearer.new(token.dup.freeze)
+      end
+
+      def self.callback(&block)
+        raise ArgumentError, "credential callback is required" unless block
+
+        Callback.new(block)
+      end
+
+      def self.helper(name = nil)
+        valid = name.nil? || (name.is_a?(String) && !name.empty? && name.bytesize <= 4096 && !name.match?(/[\r\n\0]/))
+        raise ArgumentError, "credential helper name is invalid" unless valid
+
+        Helper.new(name&.dup&.freeze)
+      end
+
+      def self.validate(value)
+        return if value.nil? || value.is_a?(Provider)
+
+        raise AuthenticationError, "credentials must be created with Thuban::Remote::Credentials"
+      end
+
+      def self.validate_basic(username, password)
+        valid_username = username.is_a?(String) && !username.empty? && !username.match?(/[:\r\n\0]/)
+        valid_password = password.is_a?(String) && !password.match?(/[\r\n\0]/)
+        raise ArgumentError, "basic credentials are invalid" unless valid_username && valid_password
+      end
+
+      private_constant :Provider, :Basic, :Bearer, :Callback, :Helper
+      private_class_method :validate_basic
+    end
+  end
+end