portage-cli 0.7.5 → 0.9.0

data/lib/portage/cli/browser_import/saver.rb

@@ -0,0 +1,62 @@
+require_relative "categorize"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # Writes an approved Importer#plan into the user's own index — only
+      # ever called after BrowserImport::Confirm said :save. A kept domain
+      # becomes an Index::Store entry with `sources: ["history"]`/
+      # `["bookmark"]`; one already in the index just gains those labels
+      # and the new category weights (its capabilities and last_verified
+      # are left for `index refresh` to re-check, same as Index::Builder's
+      # #update_existing). A domain kept because the published
+      # known-stores list already had it keeps that list's own
+      # last_verified — this import never probed it. A kept product page becomes an
+      # Index::ProductStore entry with the same `sources` labels, so
+      # Index::Exporter never publishes it.
+      class Saver
+        def initialize(stores:, products:, now: Time.now)
+          @stores = stores
+          @products = products
+          @now = now
+        end
+
+        # @return [Hash] stores:, products: — how many entries were written.
+        def save(plan)
+          kept = Array(plan[:kept])
+          products = Array(plan[:products])
+          kept.each { |entry| save_store(entry) }
+          products.each { |product| save_product(product) }
+          { stores: kept.length, products: products.length }
+        end
+
+        private
+
+        def save_store(entry)
+          existing = @stores.find(entry[:origin])
+          fields = { sources: (Array(existing && existing["sources"]) + entry[:sources]).uniq,
+                     categories: merge_categories(existing && existing["categories"], entry[:categories]) }
+          fields.merge!(new_store_fields(entry)) unless existing
+          @stores.upsert(entry[:origin], **fields)
+        end
+
+        def new_store_fields(entry)
+          { platform: nil, capabilities: Array(entry[:capabilities]), webmcp_preset: entry[:webmcp_preset],
+            last_verified: entry[:last_verified] || @now.to_i, handoff_only: entry[:handoff_only] ? true : false }
+        end
+
+        def merge_categories(existing, fresh)
+          tally = Hash.new(0)
+          [existing, fresh].each { |cats| Hash(cats).each { |id, weight| tally[id.to_s] += weight.to_i } }
+          tally.sort_by { |_id, weight| -weight }.first(Categorize::TOP_CATEGORIES).to_h
+        end
+
+        def save_product(product)
+          @products.upsert(product[:key], origin: product[:origin], seen_at: @now.to_i, title: product[:title],
+                                          brand: nil, gtin: nil, category: product[:category],
+                                          sources: [product[:source]])
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import/sqlite.rb

@@ -0,0 +1,68 @@
+require "json"
+require "open3"
+require "tmpdir"
+require "fileutils"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # Reads a browser's SQLite history database without a native gem:
+      # the database (plus its `-wal` file, when the browser left one — it
+      # holds the most recent visits until the next checkpoint) is copied
+      # into a private tmpdir first, since a running browser holds it
+      # locked, and the copy is queried with the system `sqlite3` CLI in
+      # `-readonly -json` mode. The copy is deleted before this returns,
+      # success or not. The original file is only ever read by the copy.
+      #
+      # `sqlite3` ships with macOS and every mainstream Linux distro; when
+      # it's missing, Unavailable says so rather than falling back to
+      # anything else.
+      class Sqlite
+        class Unavailable < StandardError; end
+
+        # Raised when macOS refuses to let this process read the file at
+        # all (Safari's History.db without Full Disk Access). Never worked
+        # around — see Importer's own handling.
+        class PermissionDenied < StandardError; end
+
+        # @param command [String] the sqlite3 executable — injectable so a
+        #   spec can prove the missing-binary path without uninstalling it.
+        def initialize(command: "sqlite3")
+          @command = command
+        end
+
+        # Copies `path` once and yields a query proc, so one copy serves
+        # several queries (Firefox's history and bookmarks both live in
+        # places.sqlite).
+        # @yieldparam query [Proc] `query.call(sql)` => Array<Hash>
+        def with_copy(path)
+          Dir.mktmpdir("portage-browser-import") do |dir|
+            copy = copy_database(path, dir)
+            yield ->(sql) { run(copy, sql) }
+          end
+        end
+
+        private
+
+        def copy_database(path, dir)
+          copy = File.join(dir, "copy.sqlite")
+          FileUtils.cp(path, copy)
+          FileUtils.cp("#{path}-wal", "#{copy}-wal") if File.exist?("#{path}-wal")
+          copy
+        rescue Errno::EPERM, Errno::EACCES => e
+          raise PermissionDenied, e.message
+        end
+
+        def run(copy, sql)
+          out, err, status = Open3.capture3(@command, "-readonly", "-json", copy, sql)
+          raise Unavailable, "sqlite3 failed: #{err.strip}" unless status.success?
+
+          text = out.dup.force_encoding("UTF-8").scrub
+          text.strip.empty? ? [] : JSON.parse(text)
+        rescue Errno::ENOENT
+          raise Unavailable, "the sqlite3 command isn't installed (it ships with macOS and most Linux distros)"
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import.rb

@@ -0,0 +1,23 @@
+require_relative "browser_import/filter"
+require_relative "browser_import/profiles"
+require_relative "browser_import/sqlite"
+require_relative "browser_import/plist_xml"
+require_relative "browser_import/readers"
+require_relative "browser_import/prober"
+require_relative "browser_import/importer"
+require_relative "browser_import/confirm"
+
+module Portage
+  module Cli
+    # `portage browser import` — bookmarks and history as index seeds
+    # (docs/plans/buy-skill-and-local-browser.md Phase 3, Tier A). Opt-in,
+    # local-only, reduced to shop domains, and shown to the user before
+    # anything is saved. Never reads a browser's password, cookie or
+    # autofill store (see Profiles::ALLOWED_FILES), never attaches to or
+    # drives the browser, and never sends anything about the user's
+    # history anywhere except one `/.well-known/ucp` probe per unknown
+    # domain (Prober).
+    module BrowserImport
+    end
+  end
+end

data/lib/portage/cli/browser_opener.rb

@@ -0,0 +1,38 @@
+module Portage
+  module Cli
+    # The one shell-out that opens a URL in the shopper's browser, shared by
+    # CheckoutHandoff (a dead-end checkout's auto-open) and ProductPage
+    # (docs/plans/human-pick-and-approve.md Phase 2's "view the product
+    # page"). Mixed in rather than called as a module function so `system`
+    # stays the including object's own — specs stub it per instance.
+    #
+    # No new gem for the actual open — every other shell-out in this repo
+    # (PaymentMethods::KeychainBackend, SecretServiceBackend) hand-rolls
+    # `system` rather than pulling in launchy for something the OS already
+    # provides. `system(cmd, url)` (array form, never an interpolated
+    # string) so a merchant-controlled URL can't inject into a shell.
+    # Whether a URL is safe to open at all is the caller's check.
+    module BrowserOpener
+      private
+
+      # @return [Boolean] whether the browser was actually opened.
+      def open_browser(url)
+        command = platform_command
+        return false unless command
+
+        !!system(command, url)
+      rescue StandardError => e
+        warn "portage: couldn't open #{url} (#{e.message})"
+        false
+      end
+
+      def platform_command
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/i then "open"
+        when /linux|bsd/i then "xdg-open"
+        when /mswin|mingw|cygwin/i then "start"
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/allowlist.rb

@@ -0,0 +1,40 @@
+require_relative "../handoff_only"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # The domain allowlist Phase 6 requires: driving the profile browser
+      # (evaluating WebMCP tool calls, filling checkout fields, navigating)
+      # is limited to the store being bought from, plus its checkout host
+      # once one is known. Anything else stops the run — see Bridge and
+      # DomainNotAllowedError.
+      #
+      # Reuses HandoffOnly's own host normalization/matching (a base host
+      # matches itself or any subdomain, "www." stripped, a full URL or a
+      # bare host both accepted) rather than a second copy of that logic.
+      class Allowlist
+        def initialize(hosts: [])
+          @hosts = hosts.filter_map { |h| HandoffOnly.normalize_entry(h) }
+        end
+
+        def hosts = @hosts.dup
+
+        def allowed?(host) = HandoffOnly.matches_any?(host, @hosts)
+
+        # Adds a host once it's known to be exactly what Portage itself is
+        # deliberately navigating to (the checkout URL a hand-off is about
+        # to open) — never called for a navigation a driven page made on
+        # its own; that's what #allowed? guards against.
+        # @return [String, nil] the normalized host that was added (or
+        #   already present), nil when `host_or_url` didn't parse to one.
+        def permit!(host_or_url)
+          normalized = HandoffOnly.normalize_entry(host_or_url)
+          return nil unless normalized
+
+          @hosts << normalized unless @hosts.include?(normalized)
+          normalized
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/bridge.rb

@@ -0,0 +1,120 @@
+require "uri"
+require_relative "allowlist"
+require_relative "errors"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # docs/plans/buy-skill-and-local-browser.md Phase 6: the WebMCP
+      # bridge `Cli.run_buy` hands to `Buy.new(webmcp_bridge:)` when
+      # `--handoff-target profile` — the Portage browser profile's own
+      # page target, reached over CdpSocket, wrapped so every call stays
+      # inside the domain allowlist. Everything WebMCP-shaped (#list_tools,
+      # #execute_tool, #autofill) is delegated to a real
+      # Portage::Ucp::WebMcp::Bridges::ScriptEvaluator built from this
+      # bridge's own #evaluate — this class exists to add exactly two
+      # things ScriptEvaluator doesn't have: the allowlist check on every
+      # call, and #navigate (Portage's own deliberate navigation to a
+      # checkout URL, as opposed to a page-driven one).
+      #
+      # Requires `portage-ucp-webmcp` to already be loaded — only ever
+      # built by `Cli.run_buy` after `Portage::Cli::Webmcp.available?`,
+      # same guard every other WebMCP call site in this gem already uses
+      # (see Buy#webmcp_flow) — so nothing here calls `require` itself.
+      #
+      # #headless? is always false: this is, by construction, a headed
+      # browser the shopper can see and pay in (WebMcp::Autofill's own
+      # `headless?(bridge)` check — see docs/plans/
+      # webmcp-universal-outbound.md Phase 3 — never returns
+      # :needs_headed_browser for it).
+      class Bridge
+        def initialize(socket:, allowlist:)
+          @socket = socket
+          @allowlist = allowlist
+          @page_enabled = false
+        end
+
+        def headless? = false
+
+        def location
+          raw_evaluate("Promise.resolve(window.location.href)")
+        end
+
+        # Portage's own navigation — to the checkout URL a hand-off is
+        # about to show the shopper. Permits that URL's host first (this
+        # is exactly "the store's checkout host" the allowlist is meant to
+        # grow to include, per the plan), then navigates.
+        def navigate(url)
+          host = URI.parse(url.to_s).host
+          @allowlist.permit!(host)
+          ensure_page_enabled!
+          @socket.call("Page.navigate", "url" => url.to_s)
+          nil
+        end
+
+        def list_tools = script_evaluator.list_tools
+        def execute_tool(name, input) = script_evaluator.execute_tool(name, input)
+        def autofill(fields, selectors: {}) = script_evaluator.autofill(fields, selectors: selectors)
+
+        private
+
+        def script_evaluator
+          @script_evaluator ||= Portage::Ucp::WebMcp::Bridges::ScriptEvaluator.new(evaluate: method(:evaluate),
+                                                                                   headless: false)
+        end
+
+        # Every driven call (a WebMCP tool call, an autofill attempt)
+        # checks the page's *current* location against the allowlist
+        # before running — including a navigation a previous call already
+        # caused (e.g. a preset's handoff_checkout tool navigating to
+        # checkout): that navigation's own evaluate call already ran
+        # before the page moved, so this is the first following call that
+        # can actually see where it ended up. That's the plan's "stops the
+        # run" in practice — a driven page that jumps somewhere unexpected
+        # is caught on its very next use, not mid-navigation (there's no
+        # navigation-event hook in this minimal a CDP client).
+        def evaluate(expression)
+          enforce_allowlist!
+          raw_evaluate(expression)
+        end
+
+        def enforce_allowlist!
+          host = current_host
+          return if @allowlist.allowed?(host)
+
+          raise DomainNotAllowedError,
+                "the profile browser navigated to #{host.inspect}, outside the allowed domains " \
+                "(#{@allowlist.hosts.join(', ')}) — stopping"
+        end
+
+        def current_host
+          URI.parse(raw_evaluate("Promise.resolve(window.location.href)").to_s).host
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        def raw_evaluate(expression)
+          response = @socket.call("Runtime.evaluate", "expression" => expression, "awaitPromise" => true,
+                                                      "returnByValue" => true, "userGesture" => true)
+          raise_on_exception!(response)
+          response.dig("result", "value")
+        end
+
+        def raise_on_exception!(response)
+          details = response["exceptionDetails"]
+          return unless details
+
+          text = details.dig("exception", "description") || details["text"] || "script evaluation failed"
+          raise Portage::Ucp::WebMcp::BridgeError, text
+        end
+
+        def ensure_page_enabled!
+          return if @page_enabled
+
+          @socket.call("Page.enable", {})
+          @page_enabled = true
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/browsers.rb

@@ -0,0 +1,69 @@
+require_relative "../browser_import/profiles"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # Where to find a Chromium-family browser's own executable, and
+      # which family is supported at all (docs/plans/
+      # buy-skill-and-local-browser.md Phase 6). Firefox/Safari are out of
+      # scope for driving (see the plan's Phase 6 section) even though
+      # BrowserImport::Profiles already knows their profile roots — this
+      # module only ever launches one of CHROMIUM.
+      module Browsers
+        CHROMIUM = BrowserImport::Profiles::CHROMIUM
+
+        # macOS app bundle executables. The first existing path wins.
+        MAC_APPS = {
+          "chrome" => "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+          "edge" => "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+          "brave" => "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+          "arc" => "/Applications/Arc.app/Contents/MacOS/Arc"
+        }.freeze
+
+        # Linux binary names, tried on PATH. Arc has no Linux build.
+        LINUX_BINARIES = {
+          "chrome" => %w[google-chrome google-chrome-stable chromium chromium-browser],
+          "edge" => %w[microsoft-edge microsoft-edge-stable],
+          "brave" => %w[brave-browser brave-browser-stable],
+          "arc" => []
+        }.freeze
+
+        # @param path [String] PATH-shaped, injectable so a spec can point
+        #   ".which" at a fixture directory instead of mutating ENV.
+        # @return [String, nil] the first launchable binary for `browser`
+        #   on this machine, or nil when it isn't installed.
+        def self.binary_for(browser, darwin: RUBY_PLATFORM.include?("darwin"), path: ENV.fetch("PATH", ""))
+          mac_binary(browser, darwin) || linux_binary(browser, path)
+        end
+
+        def self.mac_binary(browser, darwin)
+          return nil unless darwin
+
+          path = MAC_APPS[browser]
+          path if path && File.exist?(path)
+        end
+        private_class_method :mac_binary
+
+        def self.linux_binary(browser, path)
+          LINUX_BINARIES.fetch(browser, []).filter_map { |name| which(name, path) }.first
+        end
+        private_class_method :linux_binary
+
+        def self.which(cmd, path)
+          path.split(File::PATH_SEPARATOR).map { |dir| File.join(dir, cmd) }
+                                          .find { |candidate| File.file?(candidate) && File.executable?(candidate) }
+        end
+        private_class_method :which
+
+        # @return [String, nil] the first CHROMIUM browser that's actually
+        #   installed on this machine, reusing BrowserImport::Profiles's
+        #   own "does this browser's default profile root exist" check
+        #   purely as an installed-or-not signal — nothing under that root
+        #   is ever read here.
+        def self.detect(home: Dir.home)
+          CHROMIUM.find { |b| BrowserImport::Profiles.default_root(b, home: home) }
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/cdp.rb

@@ -0,0 +1,67 @@
+require "net/http"
+require "uri"
+require "json"
+require "portage/ucp/support/connection"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # The plain-HTTP half of Chrome DevTools Protocol: the
+      # `http://127.0.0.1:<port>/json/*` endpoints every Chromium browser
+      # exposes once started with `--remote-debugging-port`. Used for
+      # "is the profile running, and what tab is it on" (`.version`/
+      # `.list`) and to open a tab already navigated to a URL (`.new_tab`)
+      # without needing the WebSocket layer (CdpSocket) at all for that.
+      #
+      # Every call is read-only against the local debugging port, GET/PUT
+      # requests only, `route: :probe` (same route category ProbeCache's
+      # own `/.well-known/ucp` probes use) so it's subject to whatever
+      # proxy config a `--no-proxy` list already exempts localhost from.
+      # A failure (not running, timeout, bad JSON) returns nil rather than
+      # raising — callers (Profile) decide what that means.
+      module Cdp
+        TIMEOUT = 3
+        HOST = "127.0.0.1".freeze
+
+        def self.version(port:, host: HOST) = get(host, port, "/json/version")
+
+        def self.list(port:, host: HOST) = Array(get(host, port, "/json/list"))
+
+        # Opens a new tab already navigated to `url` — Chrome's own
+        # `/json/new?<url>` endpoint, a PUT since it creates something
+        # server-side.
+        def self.new_tab(port:, url:, host: HOST)
+          get(host, port, "/json/new?#{URI.encode_www_form_component(url)}", method: :put)
+        end
+
+        # `/json/close/<id>` answers plain text ("Target is closing"), not
+        # JSON — checked by success status only, never parsed as JSON.
+        def self.close_tab(port:, id:, host: HOST)
+          uri = URI("http://#{host}:#{port}/json/close/#{id}")
+          fetch(uri, :get).is_a?(Net::HTTPSuccess)
+        rescue StandardError
+          false
+        end
+
+        def self.get(host, port, path, method: :get)
+          uri = URI("http://#{host}:#{port}#{path}")
+          response = fetch(uri, method)
+          return nil unless response.is_a?(Net::HTTPSuccess)
+
+          JSON.parse(response.body)
+        rescue StandardError
+          nil
+        end
+        private_class_method :get
+
+        def self.fetch(uri, method)
+          Portage::Ucp::Support::Connection.start(uri, route: :probe, open_timeout: TIMEOUT,
+                                                       read_timeout: TIMEOUT) do |http|
+            method == :put ? http.request(Net::HTTP::Put.new(uri.request_uri)) : http.get(uri.request_uri)
+          end
+        end
+        private_class_method :fetch
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/cdp_socket.rb

@@ -0,0 +1,186 @@
+require "socket"
+require "securerandom"
+require "digest/sha1"
+require "base64"
+require "json"
+require "uri"
+require "timeout"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # A minimal, dependency-free WebSocket JSON-RPC client for a Chrome
+      # DevTools Protocol target — just enough to call `Runtime.evaluate`/
+      # `Page.navigate`/`Page.enable` on a page's own `webSocketDebuggerUrl`
+      # synchronously, one request at a time. Not a general WebSocket
+      # client: text frames only, no compression extension, and no
+      # concurrent in-flight requests — Bridge never has two CDP calls
+      # outstanding at once, so `#call` blocks until its own response (by
+      # `id`) comes back, discarding any unsolicited event frame in
+      # between.
+      #
+      # `transport:` is injectable (any object answering `#write`/`#read`/
+      # `#close`, e.g. a real TCPSocket) so specs never open a real socket
+      # — see cdp_socket_spec.rb.
+      class CdpSocket
+        GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11".freeze
+        TIMEOUT = 30
+
+        def self.connect(ws_url, transport: nil, timeout: TIMEOUT)
+          uri = URI.parse(ws_url)
+          transport ||= TCPSocket.new(uri.host, uri.port)
+          handshake!(transport, uri, timeout: timeout)
+          new(transport)
+        end
+
+        def initialize(transport)
+          @transport = transport
+          @next_id = 1
+        end
+
+        # @return [Hash] the CDP "result" object.
+        # @raise [RuntimeError] the CDP "error" object's message, when the
+        #   browser itself rejected the command (bad method/params, no
+        #   such target) — distinct from an *evaluated script* raising,
+        #   which comes back as a normal result with `exceptionDetails`.
+        def call(method, params = {})
+          id = @next_id
+          @next_id += 1
+          send_frame(JSON.generate(id: id, method: method, params: params))
+          await_response(id)
+        end
+
+        def close
+          @transport.close
+        rescue StandardError
+          nil
+        end
+
+        private
+
+        def await_response(id)
+          loop do
+            message = JSON.parse(read_message)
+            next if message["id"] != id
+
+            raise message.dig("error", "message").to_s if message["error"]
+
+            return message["result"] || {}
+          end
+        end
+
+        # --- outbound framing (client -> server frames MUST be masked,
+        # RFC 6455 §5.1) ---
+
+        def send_frame(payload)
+          bytes = payload.b
+          mask = SecureRandom.random_bytes(4)
+          @transport.write(frame_header(0x1, bytes.bytesize) + mask + xor(bytes, mask))
+        end
+
+        def send_pong(payload)
+          bytes = payload.to_s.b
+          mask = SecureRandom.random_bytes(4)
+          @transport.write(frame_header(0xA, bytes.bytesize) + mask + xor(bytes, mask))
+        end
+
+        def frame_header(opcode, length)
+          first = 0x80 | opcode # FIN=1
+          return [first, 0x80 | length].pack("CC") if length <= 125
+          return [first, 0x80 | 126, length].pack("CCn") if length <= 0xFFFF
+
+          [first, 0x80 | 127, length].pack("CCQ>")
+        end
+
+        def xor(bytes, mask)
+          bytes.each_byte.with_index.map { |byte, i| byte ^ mask.getbyte(i % 4) }.pack("C*")
+        end
+
+        # --- inbound framing (server -> client frames are never masked)
+        # ---
+
+        # Reads whole logical messages (following any continuation
+        # frames), answering pings and dropping pongs, until it has one
+        # worth handing to #await_response.
+        def read_message
+          buffer = +""
+          loop do
+            fin, opcode, payload = read_one_frame
+            case opcode
+            when 0x9 then send_pong(payload)
+            when 0x8 then raise "CDP socket closed by the browser"
+            when 0xA then nil
+            else buffer << payload
+            end
+            return buffer if fin && [0x0, 0x1].include?(opcode)
+          end
+        end
+
+        def read_one_frame
+          b1, b2 = read_exactly(2).unpack("CC")
+          fin = b1[7] == 1
+          opcode = b1 & 0x0F
+          masked = b2[7] == 1
+          [fin, opcode, read_payload(b2 & 0x7F, masked)]
+        end
+
+        def read_payload(length, masked)
+          length = read_exactly(2).unpack1("n") if length == 126
+          length = read_exactly(8).unpack1("Q>") if length == 127
+          mask = read_exactly(4) if masked
+          payload = length.positive? ? read_exactly(length) : +""
+          mask ? xor(payload, mask) : payload
+        end
+
+        def read_exactly(length)
+          return +"" if length <= 0
+
+          Timeout.timeout(TIMEOUT) do
+            data = +""
+            while data.bytesize < length
+              chunk = @transport.read(length - data.bytesize)
+              raise "CDP socket closed by the browser" if chunk.nil?
+
+              data << chunk
+            end
+            data
+          end
+        end
+
+        # --- handshake (RFC 6455 §4) ---
+
+        def self.handshake!(transport, uri, timeout:)
+          key = SecureRandom.base64(16)
+          Timeout.timeout(timeout) { transport.write(handshake_request(uri, key)) }
+          headers = Timeout.timeout(timeout) { read_headers(transport) }
+          verify_handshake!(headers, key)
+        end
+        private_class_method :handshake!
+
+        def self.handshake_request(uri, key)
+          path = uri.path.to_s.empty? ? "/" : uri.path
+          path += "?#{uri.query}" if uri.query
+          "GET #{path} HTTP/1.1\r\nHost: #{uri.host}:#{uri.port}\r\nUpgrade: websocket\r\n" \
+            "Connection: Upgrade\r\nSec-WebSocket-Key: #{key}\r\nSec-WebSocket-Version: 13\r\n\r\n"
+        end
+        private_class_method :handshake_request
+
+        def self.read_headers(transport)
+          data = +""
+          data << transport.read(1) until data.end_with?("\r\n\r\n")
+          data
+        end
+        private_class_method :read_headers
+
+        def self.verify_handshake!(headers, key)
+          raise "CDP handshake failed: #{headers.lines.first}" unless headers.start_with?("HTTP/1.1 101")
+
+          expected = Base64.strict_encode64(Digest::SHA1.digest(key + GUID))
+          accept = headers[/Sec-WebSocket-Accept:\s*(\S+)/i, 1]
+          raise "CDP handshake failed: unexpected Sec-WebSocket-Accept" unless accept == expected
+        end
+        private_class_method :verify_handshake!
+      end
+    end
+  end
+end