obxcura 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f2f8eab2a1520c5f96b85a50ddafee3b7938cd88014e1b288bb4d7a2839454ba
+  data.tar.gz: 2d81b467a60b702cfeea5d90792d184f2362f9f2bf96f9a26fdfce68929be12d
+SHA512:
+  metadata.gz: 43e149575bda036ff64b42670f8b86147999142538cc89f459bace265ac3cef2f1feccbea1dda40adec6dbed151958d8ae8d2f40941f40155093226e8cf8232e
+  data.tar.gz: ea2770f6a9799e45ab8d1dbbb7c79a7b62c621305831a319f182d7cae3fdc2f257f0a49be55d1757e387065bc6e52ae4d596d0165599d76f501d8ae6ebcaec99

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+## [Unreleased]
+
+## [0.1.1] - 2026-07-14
+
+### Fixed
+
+- Corrected gemspec repository URLs (`homepage`, `source_code_uri`,
+  `changelog_uri`) to point at the actual GitHub repository.
+
+## [0.1.0] - 2026-07-09
+
+Initial release. A Ruby client that drives the Obscura headless browser over
+the Chrome DevTools Protocol.
+
+### Added
+
+- `Browser` — target lifecycle over a single WebSocket, cookie management
+  (`cookies`, `clear_cookies`), and `quit`.
+- `Page` — navigation with load waiting, `evaluate`, DOM access, form filling,
+  JSON/form XHR POSTs, and network logging. Each page is a CDP target with its
+  own attached session, multiplexed over the shared socket.
+- `Client` — WebSocket transport built directly on `websocket-driver`, with a
+  single reader thread routing command replies by `id` and events by
+  `sessionId`.
+- `Frame` (with `Runtime` and `DOM` mixins) and `Node` helpers for scripting
+  and DOM queries.
+- Chunked reads (`read_string`) so large-string getters like `Page#html`
+  work around Obscura's ~500–700 KB single-message ceiling.
+- Optional `nokogiri` integration in `Page#dom`, lazily required.
+- Integration test suite that boots one `obscura serve` plus a local WEBrick
+  site, tagged `:obscura` and skipped when no browser binary is available.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Guillermo Moreno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,169 @@
+# Obxcura
+
+A small Ruby client for the [Obscura](https://github.com/h4ckf0r0day/obscura)
+headless browser, driven over the Chrome DevTools Protocol.
+
+A `Browser` owns one WebSocket connection; each `Page` is a CDP target with its
+own attached session. One connection, many pages.
+
+> **Obxcura vs Obscura.** This gem is `Obxcura`. The browser it drives is
+> `obscura` — a separate binary you run yourself. The `x` keeps them apart.
+
+## Installation
+
+```bash
+bundle add obxcura
+```
+
+You also need the `obscura` binary on your `PATH`
+([releases](https://github.com/h4ckf0r0day/obscura/releases)).
+
+## Usage
+
+Start the browser first (defaults to port 9222):
+
+```bash
+obscura serve
+```
+
+Then:
+
+```ruby
+require "obxcura"
+
+browser = Obxcura::Browser.new     # or Obxcura.start
+page    = browser.go_to("https://example.com")
+
+page.html                          # rendered DOM, post-JS
+page.title                         # "Example Domain"
+page.current_url                   # "https://example.com/"
+page.evaluate("1 + 2")             # => 3
+
+browser.quit
+```
+
+### Querying the DOM
+
+`#at_css` / `#css` return live `Obxcura::Node` handles backed by the real DOM:
+
+```ruby
+page.at_css("h1").text             # => "Example Domain"
+page.at_css("a")["href"]           # attribute value, or nil
+page.at_css("h1").outer_html       # "<h1>Example Domain</h1>"
+page.css("p").map(&:text)          # every <p>'s text
+page.at_css("#missing")            # => nil
+```
+
+### Running JavaScript
+
+Pass Ruby values as arguments — they cross into the page as real values
+(`arguments[0]`, `arguments[1]`, …), never string-interpolated into source:
+
+```ruby
+page.evaluate("arguments[0] * 2", 21)          # => 42
+
+# `evaluate_func` calls a function declaration directly:
+page.evaluate_func(<<~JS, "h1")
+  function(sel) { return document.querySelector(sel).textContent; }
+JS
+```
+
+### POSTing from inside the page
+
+Obscura routes `XMLHttpRequest` but not `fetch`, so `#xhr_post` runs the POST
+from the page's context (reusing its cookies). Values cross as arguments:
+
+```ruby
+result = page.xhr_post(
+  "https://example.com/api/login",
+  URI.encode_www_form(user: "me", pass: "secret"),   # payload
+  "application/x-www-form-urlencoded",                # content type
+  { "X-Requested-With" => "XMLHttpRequest" }          # headers
+)
+
+result["status"]   # => 200
+result["ok"]       # => true  (2xx)
+result["body"]     # response text
+```
+
+Any HTTP reply (including 4xx/5xx) comes back as `{ "status", "ok", "body" }`.
+A transport failure — the request never reached the server (CORS, the
+private-network SSRF guard, mixed origin, a dead host) — raises
+`Obxcura::ConnectionError`. If the server accepts the connection but never
+answers, the wait ends with `Obxcura::TimeoutError`; pass `timeout:` (seconds)
+to bound it. Some anti-bot endpoints tarpit non-stealth clients — try
+`obscura serve --stealth`.
+
+## API
+
+`Obxcura.start(**opts)` is sugar for `Obxcura::Browser.new`.
+
+- **`Obxcura::Browser`** — `.new(host:, port:, timeout:)`, `#create_page(url)`,
+  `#go_to`/`#goto`, `#targets`, `#version`, `#command`, `#close`/`#quit`.
+  Readers: `#client`, `#pages`, `#host`, `#port`.
+- **`Obxcura::Page`** — `#goto`/`#go_to`, `#evaluate`, `#evaluate_func`,
+  `#html`/`#body`, `#title`, `#current_url`, `#at_css`, `#css`, `#xhr_post`,
+  `#cookies`, `#refresh`/`#reload`, `#command`, `#close`, `#close_connection`.
+  Readers: `#frame`, `#target_id`, `#session_id`, `#client`.
+- **`Obxcura::Node`** (from `#at_css`/`#css`) — `#text`, `#[]` (attribute),
+  `#outer_html`, `#object_id`.
+- **`Obxcura::Frame`** — the main frame behind a Page; carries the DOM/Runtime
+  methods Page delegates (`#evaluate`, `#at_css`, `#read_string`, …).
+- **`Obxcura::Client`** — the CDP transport, if you need raw `#command`,
+  `#subscribe` / `#unsubscribe`, or `#close`.
+
+Errors all descend from `Obxcura::Error`: `TimeoutError`, `ProtocolError`,
+`ConnectionError`.
+
+## Obscura's quirks (and how Obxcura handles them)
+
+These are properties of the **Obscura browser**, not of this gem. They shape the
+API, so they're worth knowing:
+
+- **No paint engine.** There is no screenshot API, and there never will be one
+  here. `Page.captureScreenshot` is unusable.
+- **~500–700 KB message ceiling.** Obscura won't send a single CDP message
+  larger than that. `Page#html` works around it by snapshotting `outerHTML` into
+  a page global and pulling it back in 400 KB slices. Don't return giant values
+  from `#evaluate` directly.
+- **DOM nodes don't serialize.** A node returned by value comes back as an
+  internal stub, so `#at_css` / `#css` resolve it (via `DOM.resolveNode`) to a
+  live handle and read it with `Runtime.callFunctionOn`.
+- **XHR, not fetch.** Obscura routes `XMLHttpRequest` but not `fetch`, so
+  `#xhr_post` uses XHR from the page context. It also ignores
+  `XMLHttpRequest#timeout`, so the effective bound is the CDP-level `timeout:`.
+- **Persistent cookies.** `obscura serve` is long-lived and its cookie jar
+  survives `#quit` (that only drops the WebSocket). Read them with
+  `page.cookies`; closing a page clears the browser's cookie jar.
+- **Private networks are blocked by default.** To drive a local site, start the
+  browser with `obscura serve --allow-private-network`.
+
+The transport is built directly on `websocket-driver` rather than
+`websocket-client-simple`, which reads a byte at a time and wedges on large
+frames.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake          # rubocop + rspec
+bundle exec rake doc      # YARD docs into doc/
+bin/console               # IRB with the gem loaded
+```
+
+The integration specs boot a real `obscura serve` against a local WEBrick test
+site. Point them at your binary:
+
+```bash
+OBSCURA_BIN=/path/to/obscura bundle exec rspec
+```
+
+Without the binary those specs skip cleanly, so `bundle exec rspec` still passes.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/memoxmrdl/obxcura.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/obxcura/browser.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Obxcura
+  # The entry point. Owns one Client (one connection) and the pages opened on it.
+  #
+  #   browser = Obxcura::Browser.new
+  #   page    = browser.create_page
+  #   browser.quit
+  #
+  # Assumes a running `obscura serve` (default 127.0.0.1:9222). Pass host:/port:
+  # to point elsewhere.
+  class Browser
+    extend Forwardable
+
+    # @return [String] default host for `obscura serve`.
+    DEFAULT_HOST = "127.0.0.1"
+    # @return [Integer] default CDP port for `obscura serve`.
+    DEFAULT_PORT = 9222
+
+    # @return [Obxcura::Client] the underlying CDP transport.
+    # @return [Array<Obxcura::Page>] the pages currently open.
+    # @return [String] the browser host.
+    # @return [Integer] the browser port.
+    attr_reader :client, :pages, :host, :port
+
+    delegate %i[command] => :client
+
+    # Connect to a running `obscura serve`.
+    #
+    # @param host [String] host the browser listens on.
+    # @param port [Integer] CDP port the browser listens on.
+    # @param timeout [Integer] default seconds to wait for CDP replies.
+    # @raise [Obxcura::ConnectionError] if the browser can't be reached.
+    def initialize(host: DEFAULT_HOST, port: DEFAULT_PORT, timeout: Client::DEFAULT_TIMEOUT)
+      @host = host
+      @port = port
+      @timeout = timeout
+      @pages = []
+      @client = Client.new(browser_ws_url, timeout: @timeout)
+    end
+
+    # Open a fresh page (a CDP target) and attach to it.
+    #
+    # @param url [String] URL to open the target at (defaults to a blank page).
+    # @return [Obxcura::Page] the new, tracked page.
+    def create_page(url = "about:blank")
+      target_id = command("Target.createTarget", { url: url })["targetId"]
+      session_id = command("Target.attachToTarget", { targetId: target_id, flatten: true })["sessionId"]
+
+      page = Page.new(self, target_id: target_id, session_id: session_id)
+      @pages << page
+      page
+    end
+
+    # Open a page and navigate to `url` in one call.
+    #
+    # Navigates from a blank target rather than passing the URL straight to
+    # Target.createTarget: creating two URL-loaded targets and then evaluating
+    # crashes `obscura serve` (connection closed: end of file reached).
+    #
+    # @param url [String] URL to navigate to.
+    # @return [Obxcura::Page] the navigated page (load event fired).
+    def go_to(url)
+      create_page.goto(url)
+    end
+    alias goto go_to
+
+    # Every target the browser knows about (pages, workers, ...).
+    #
+    # @return [Array<Hash>] raw CDP `TargetInfo` hashes.
+    def targets
+      command("Target.getTargets")["targetInfos"]
+    end
+
+    # The browser's `/json/version` metadata (product, protocol, ws endpoint).
+    #
+    # @return [Hash] the decoded JSON version document.
+    def version
+      uri = URI("http://#{@host}:#{@port}/json/version")
+      JSON.parse(Net::HTTP.get(uri))
+    end
+
+    # Stop tracking a page. Called by {Obxcura::Page#close}.
+    #
+    # @param page [Obxcura::Page] the page to forget.
+    # @return [Obxcura::Page, nil] the removed page, or nil if unknown.
+    def remove_page(page)
+      @pages.delete(page)
+    end
+
+    # Close every page, then drop the connection. Aliased as `quit`.
+    #
+    # @return [void]
+    def close
+      @pages.dup.each(&:close)
+      client.close
+    end
+    alias quit close
+
+    private
+
+    def browser_ws_url
+      info = version
+      info["webSocketDebuggerUrl"] ||
+        raise(ConnectionError, "No browser endpoint at #{@host}:#{@port}")
+    rescue SystemCallError, SocketError => e
+      raise ConnectionError,
+        "Could not reach Obscura at #{@host}:#{@port} (#{e.message}). Is it running? Start it with: obscura serve"
+    end
+  end
+end

data/lib/obxcura/client.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "socket"
+require "openssl"
+require "websocket/driver"
+
+module Obxcura
+  # The CDP transport: a single WebSocket to the browser endpoint.
+  #
+  # Built directly on websocket-driver, because the higher-level
+  # websocket-client-simple reads the socket one byte at a time (`@socket.getc`)
+  # — a ~1MB CDP frame there takes seconds and can wedge the read loop. Here a
+  # single reader thread pumps raw bytes through the driver (`readpartial` +
+  # `driver.parse`), which parses frames efficiently.
+  #
+  # This object *is* the driver's I/O adapter: websocket-driver calls #url for the
+  # handshake and #write to put bytes on the wire.
+  #
+  # Everything on the wire is multiplexed over this one socket. Command replies
+  # come back keyed by the `id` we assigned (globally unique across the
+  # connection), so we resolve those regardless of session. Events instead carry
+  # a `sessionId`, so we fan them out to whichever Page subscribed for that
+  # session. Browser-level events (no sessionId) go to the `:browser` slot.
+  class Client
+    # @return [Integer] default seconds to wait for a command reply.
+    DEFAULT_TIMEOUT = 30
+
+    # Obscura frames stay well under this; it's just a guard against a runaway
+    # allocation — a sane cap on the receive size.
+    #
+    # @return [Integer] largest CDP frame (bytes) the driver will assemble.
+    MAX_MESSAGE_SIZE = 64 * 1024 * 1024
+
+    # Bytes pulled per read syscall. Small is fine — the driver reassembles
+    # frames across reads; this only bounds how much we buffer at once.
+    #
+    # @return [Integer]
+    READ_CHUNK = 512
+
+    # @return [String] the WebSocket URL of the browser endpoint.
+    attr_reader :url
+
+    # Open the WebSocket to the browser and block until the handshake completes.
+    #
+    # @param url [String] the `ws://`/`wss://` browser endpoint.
+    # @param timeout [Integer] default seconds to wait for command replies.
+    # @raise [Obxcura::TimeoutError] if the connection can't be established.
+    def initialize(url, timeout: DEFAULT_TIMEOUT)
+      @url = url
+      @timeout = timeout
+      @command_id = 0
+      @mutex = Mutex.new
+      @write_mutex = Mutex.new
+      @pending = {}
+      @subscribers = {}
+      @open = Queue.new
+      connect
+    end
+
+    # Send a CDP command and block until its reply arrives.
+    #
+    # @param method [String] the CDP method name, e.g. "Runtime.evaluate".
+    # @param params [Hash] the method parameters.
+    # @param session_id [String, nil] nil sends a browser-level command (target
+    #   management); a session id routes it to a specific page.
+    # @param timeout [Integer] seconds to wait for the reply.
+    # @return [Hash] the command's `result` object.
+    # @raise [Obxcura::TimeoutError] if no reply arrives in time.
+    # @raise [Obxcura::ProtocolError] if the browser returns an error.
+    def command(method, params = {}, session_id: nil, timeout: @timeout)
+      id = next_id
+      queue = Queue.new
+      @mutex.synchronize { @pending[id] = queue }
+
+      frame = { id: id, method: method, params: params }
+      frame[:sessionId] = session_id if session_id
+      @driver.text(JSON.generate(frame))
+
+      message = Timeout.timeout(timeout, TimeoutError, "#{method} timed out after #{timeout}s") { queue.pop }
+      raise ProtocolError, message["error"]["message"] if message["error"]
+
+      message["result"]
+    ensure
+      @mutex.synchronize { @pending.delete(id) }
+    end
+
+    # Register a handler for events on a given session.
+    #
+    # @param session_id [String, Symbol] the page session id, or `:browser` for
+    #   target-level (session-less) events.
+    # @yieldparam method [String] the CDP event name.
+    # @yieldparam params [Hash] the event parameters.
+    # @return [Proc] the stored handler.
+    def subscribe(session_id, &block)
+      @subscribers[session_id] = block
+    end
+
+    # Remove the handler previously registered for a session.
+    #
+    # @param session_id [String, Symbol] the session to stop listening on.
+    # @return [Proc, nil] the removed handler, if any.
+    def unsubscribe(session_id)
+      @subscribers.delete(session_id)
+    end
+
+    # Close the driver, socket and reader thread. Safe to call more than once.
+    #
+    # @return [void]
+    def close
+      @closing = true
+      @driver&.close
+      @socket&.close
+      @reader&.kill
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    # @return [Boolean] whether the connection is being (or has been) torn down.
+    def closing?
+      @closing == true
+    end
+
+    # I/O adapter for websocket-driver: puts outgoing bytes on the wire. Writes
+    # are serialized so command threads and the driver's own control frames
+    # (ping/pong/close) never interleave and corrupt the stream.
+    #
+    # @param data [String] raw bytes to write.
+    # @return [void]
+    def write(data)
+      @write_mutex.synchronize { @socket.write(data) }
+    rescue IOError, SystemCallError => e
+      warn "[Obxcura] websocket write error: #{e}" unless closing?
+    end
+
+    private
+
+    def connect
+      @socket = open_socket
+      @driver = ::WebSocket::Driver.client(self, max_length: MAX_MESSAGE_SIZE)
+
+      @driver.on(:open) { @open.push(true) }
+      @driver.on(:message) { |event| handle_message(event.data) }
+      @driver.on(:close) { |event| handle_disconnect(event) }
+      @driver.on(:error) { |event| warn "[Obxcura] websocket error: #{event.message}" unless closing? }
+
+      start_reader
+      @driver.start
+
+      Timeout.timeout(@timeout, TimeoutError, "Could not connect to #{@url}") { @open.pop }
+    end
+
+    def open_socket
+      uri = URI(@url)
+      tcp = TCPSocket.new(uri.host, uri.port || (uri.scheme == "wss" ? 443 : 80))
+      return tcp unless uri.scheme == "wss"
+
+      ssl = OpenSSL::SSL::SSLSocket.new(tcp, OpenSSL::SSL::SSLContext.new)
+      ssl.sync_close = true
+      ssl.hostname = uri.host
+      ssl.connect
+      ssl
+    end
+
+    # One reader thread feeds raw bytes to the driver, which emits :message as
+    # frames complete. A raised parse is logged (not fatal); a dead socket ends
+    # the loop and wakes any in-flight commands so they don't hang to timeout.
+    def start_reader
+      @reader = Thread.new do
+        until closing?
+          begin
+            @driver.parse(@socket.readpartial(READ_CHUNK))
+          rescue EOFError, IOError, SystemCallError => e
+            handle_disconnect(e) unless closing?
+            break
+          rescue StandardError => e
+            warn "[Obxcura] reader error: #{e}" unless closing?
+          end
+        end
+      end
+    end
+
+    def handle_message(data)
+      message = JSON.parse(data)
+
+      if message["id"]
+        queue = @mutex.synchronize { @pending[message["id"]] }
+        queue&.push(message)
+      elsif message["method"]
+        handler = @subscribers[message["sessionId"] || :browser]
+        handler&.call(message["method"], message["params"])
+      end
+    rescue JSON::ParserError => e
+      warn "[Obxcura] dropped unparseable message: #{e}" unless closing?
+    end
+
+    # The socket dropped (or the browser closed us). Fail every waiting command
+    # so callers get a prompt error instead of a 30s timeout.
+    def handle_disconnect(reason)
+      description = reason.respond_to?(:message) ? reason.message : reason.to_s
+      @mutex.synchronize do
+        @pending.each_value { |queue| queue.push({ "error" => { "message" => "connection closed: #{description}" } }) }
+      end
+    end
+
+    def next_id
+      @mutex.synchronize { @command_id += 1 }
+    end
+  end
+end

data/lib/obxcura/frame/dom.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Obxcura
+  class Frame
+    # DOM: high-level reads of the rendered page, all built on Runtime.
+    #
+    # Selector queries return live Nodes. Obscura serializes a DOM node over
+    # returnByValue as an internal stub carrying an `_nid` — useless on its own,
+    # but the `_nid` resolves (DOM.resolveNode) to a real remote object handle we
+    # wrap in a Node and drive with Runtime#call_on.
+    module DOM
+      # @return [String] the current top-window URL.
+      def current_url
+        evaluate("window.location.href")
+      end
+
+      # @return [String] the current document title.
+      def title
+        evaluate("document.title")
+      end
+
+      # The live, post-JS HTML. Retrieved in chunks (see {Runtime#read_string})
+      # because a full page's outerHTML routinely exceeds Obscura's message limit.
+      # Aliased as `html`.
+      #
+      # @return [String] the rendered document's outer HTML.
+      def body
+        read_string("document.documentElement.outerHTML")
+      end
+      alias_method :html, :body
+
+      # First element matching a CSS selector.
+      #
+      # @param selector [String] a CSS selector.
+      # @return [Obxcura::Node, nil] the matching node, or nil if none.
+      def at_css(selector)
+        to_node(evaluate_func("function(s) { return document.querySelector(s); }", selector))
+      end
+
+      # All elements matching a CSS selector.
+      #
+      # @param selector [String] a CSS selector.
+      # @return [Array<Obxcura::Node>] the matching nodes (empty if none).
+      def css(selector)
+        Array(evaluate_func("function(s) { return Array.from(document.querySelectorAll(s)); }", selector))
+          .filter_map { |stub| to_node(stub) }
+      end
+
+      private
+
+      # Resolve Obscura's serialized node stub ({"_nid"=>N,...}) into a Node.
+      #
+      # @param stub [Hash, nil] the serialized node from a querySelector call.
+      # @return [Obxcura::Node, nil] a live node handle, or nil for a blank match.
+      def to_node(stub)
+        return nil unless stub.is_a?(Hash) && stub["_nid"]
+
+        object_id = command("DOM.resolveNode", { nodeId: stub["_nid"] }).dig("object", "objectId")
+
+        Node.new(self, object_id)
+      end
+    end
+  end
+end

data/lib/obxcura/frame/runtime.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Obxcura
+  class Frame
+    # Runtime: executing JavaScript in the frame's context. This is the side that
+    # reaches the Client and puts CDP commands on the wire; everything in DOM is
+    # built on top of #evaluate.
+    #
+    # Ruby values cross into JS as real arguments (Runtime.callFunctionOn), not by
+    # being string-interpolated into source. Node-handle resolution, cyclic-node
+    # detection and a retry loop are deliberately left out.
+    module Runtime
+      # Obscura won't send a single CDP message larger than ~500-700KB, so we pull
+      # large strings back in slices this size and stitch them together. Well under
+      # the ceiling, and each slice is fast over the websocket-driver transport.
+      #
+      # @return [Integer] slice size (bytes) used by {#read_string}.
+      EVALUATE_CHUNK = 400_000
+
+      # Evaluate a JS expression and return its value (awaits promises).
+      #
+      # Extra args are passed to the page as real values, reachable in the
+      # expression as `arguments[0]`, `arguments[1]`, ... Without args it's a
+      # single Runtime.evaluate (the hot path); with args it goes through
+      # Runtime.callFunctionOn so nothing is interpolated into source.
+      #
+      # @param expression [String] the JS expression to evaluate.
+      # @param args [Array] values passed to the page as `arguments[...]`.
+      # @return [Object, nil] the evaluated value (JSON-decoded).
+      # @raise [Obxcura::ProtocolError] if the JS throws.
+      # @example
+      #   frame.evaluate("arguments[0] + arguments[1]", 2, 3)   # => 5
+      def evaluate(expression, *args)
+        return handle_result(evaluate_command(expression)) if args.empty?
+
+        evaluate_func("function() { return (#{expression}); }", *args)
+      end
+
+      # Call a JS function declaration with the given arguments, bound to the live
+      # global object. Unlike {#evaluate}, `expression` is the function itself.
+      #
+      # @param expression [String] a JS function declaration.
+      # @param args [Array] values passed to the function.
+      # @param timeout [Integer, nil] override for the client's reply timeout.
+      # @return [Object, nil] the function's return value (JSON-decoded).
+      # @raise [Obxcura::ProtocolError] if the JS throws.
+      # @example
+      #   frame.evaluate_func("function(sel){ return document.querySelector(sel) }", "#id")
+      def evaluate_func(expression, *args, timeout: nil)
+        call_on(global_object_id, expression, args, timeout: timeout)
+      end
+
+      # Call a function declaration bound to a specific remote object (its `this`).
+      # Used by {#evaluate_func} (bound to globalThis) and by {Node} reads (bound
+      # to the node's handle).
+      #
+      # @param object_id [String] the CDP objectId to bind as `this`.
+      # @param function_declaration [String] a JS function declaration.
+      # @param args [Array] values passed to the function.
+      # @param timeout [Integer, nil] override for the client's reply timeout,
+      #   e.g. for a call that awaits a slow in-page POST.
+      # @return [Object, nil] the function's return value (JSON-decoded).
+      # @raise [Obxcura::ProtocolError] if the JS throws.
+      def call_on(object_id, function_declaration, args = [], timeout: nil)
+        handle_result(command(
+          "Runtime.callFunctionOn",
+          {
+            functionDeclaration: function_declaration,
+            objectId: object_id,
+            arguments: args.map { |value| { value: value } },
+            awaitPromise: true,
+            returnByValue: true
+          },
+          timeout: timeout
+        ))
+      end
+
+      # Pull a possibly-large JS string back in {EVALUATE_CHUNK}-sized slices. The
+      # expression is snapshotted into a page global once, so it's evaluated a
+      # single time no matter how big the result is; we then slice that global.
+      #
+      # @param js_expression [String] a JS expression producing a string.
+      # @return [String] the full string, reassembled from slices.
+      def read_string(js_expression)
+        length = evaluate("(window.__obxcura_read = String(#{js_expression})).length").to_i
+        return "" if length.zero?
+
+        buffer = String.new(capacity: length)
+        offset = 0
+        while offset < length
+          buffer << evaluate("window.__obxcura_read.slice(#{offset}, #{offset + EVALUATE_CHUNK})")
+          offset += EVALUATE_CHUNK
+        end
+        buffer
+      end
+
+      private
+
+      # objectId of the live global object, fetched fresh so it can't go stale
+      # across navigations — no execution-context tracking needed.
+      def global_object_id
+        evaluate_command("globalThis", by_value: false).dig("result", "objectId")
+      end
+
+      def evaluate_command(expression, by_value: true)
+        command("Runtime.evaluate", { expression: expression, awaitPromise: true, returnByValue: by_value })
+      end
+
+      def handle_result(result)
+        if result["exceptionDetails"]
+          raise ProtocolError, result.dig("exceptionDetails", "text") || "JS execution error"
+        end
+
+        result.dig("result", "value")
+      end
+
+      def command(method, params = {}, timeout: nil)
+        options = { session_id: page.session_id }
+        options[:timeout] = timeout if timeout
+        page.client.command(method, params, **options)
+      end
+    end
+  end
+end

data/lib/obxcura/frame.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "frame/runtime"
+require_relative "frame/dom"
+
+module Obxcura
+  # A browsing context inside a Page. It ties together Runtime (executing JS via
+  # the Client) and DOM (reads built on that), and reaches the transport through
+  # its owning Page — so a Frame never touches the Client directly except via
+  # `page.client`.
+  #
+  # Obxcura drives a single main frame per page today (id == the page's
+  # target_id); there is deliberately no iframe tree.
+  class Frame
+    include Runtime
+    include DOM
+
+    # @return [String] the frame's unique id (the page's CDP target_id).
+    attr_accessor :id
+
+    # @return [Obxcura::Page] the page that owns this frame.
+    attr_reader :page
+
+    # @param id [String] the frame id (its page's target_id).
+    # @param page [Obxcura::Page] the owning page, used to reach the Client.
+    def initialize(id, page)
+      @id = id
+      @page = page
+    end
+
+    # @return [String] the frame's current URL.
+    def url
+      evaluate("window.location.href")
+    end
+
+    # @return [String] the frame's current document title.
+    def title
+      evaluate("document.title")
+    end
+  end
+end

data/lib/obxcura/node.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Obxcura
+  # A live handle to a DOM node inside a Frame. Backed by a CDP remote object, so
+  # reads run as function calls bound to that object and reflect the current DOM.
+  # Returned by Frame::DOM#at_css / #css.
+  class Node
+    # @return [String] the CDP remote objectId backing this node.
+    attr_reader :object_id
+
+    # @param frame [Obxcura::Frame] the frame the node lives in.
+    # @param object_id [String] the CDP objectId of the node.
+    def initialize(frame, object_id)
+      @frame = frame
+      @object_id = object_id
+    end
+
+    # @return [String] the visible text of the node and its descendants.
+    def text
+      @frame.call_on(@object_id, "function() { return this.textContent; }")
+    end
+
+    # Read an attribute value.
+    #
+    # @param name [String] the attribute name.
+    # @return [String, nil] the attribute value, or nil if absent.
+    def [](name)
+      @frame.call_on(@object_id, "function(name) { return this.getAttribute(name); }", [ name ])
+    end
+
+    # @return [String] the node's serialized outer HTML.
+    def outer_html
+      @frame.call_on(@object_id, "function() { return this.outerHTML; }")
+    end
+  end
+end

data/lib/obxcura/page.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Obxcura
+  # A single page/tab: a CDP target with its own attached session. Created via
+  # {Obxcura::Browser#create_page} — you rarely instantiate this directly.
+  #
+  # Page owns the CDP session, navigation, in-page POSTs and lifecycle. Reading
+  # the DOM and executing JS belong to its main {Frame} (see {Frame::DOM} and
+  # {Frame::Runtime}), and Page delegates those (`#evaluate`, `#html`, `#title`,
+  # `#at_css`, ...).
+  #
+  # Obscura has no paint engine, so there is deliberately no screenshot API.
+  #
+  # @example
+  #   page = browser.create_page
+  #   page.goto("https://example.com")
+  #   page.html                 # rendered DOM after JS
+  #   page.title                # "Example Domain"
+  #   page.at_css("h1").text    # => "Example Domain"
+  #   page.close
+  class Page
+    extend Forwardable
+
+    # @return [String] the CDP target id backing this page.
+    # @return [String] the CDP session id attached to the target.
+    # @return [Obxcura::Client] the shared CDP transport.
+    # @return [Obxcura::Frame] the page's main frame.
+    attr_reader :target_id, :session_id, :client, :frame
+
+    # Delegated to the main {Frame}: `#evaluate`, `#evaluate_func`,
+    # `#current_url`, `#title`, `#html`, `#body`, `#at_css`, `#css`.
+    def_delegators :frame, :evaluate, :evaluate_func, :current_url, :title, :html, :body, :at_css, :css
+
+    # @param browser [Obxcura::Browser] the owning browser.
+    # @param target_id [String] the CDP target id.
+    # @param session_id [String] the CDP session attached to the target.
+    def initialize(browser, target_id:, session_id:)
+      @browser = browser
+      @client = browser.client
+      @target_id = target_id
+      @session_id = session_id
+      @frame = Frame.new(target_id, self)
+      @load_queue = Queue.new
+      @network_log = []
+      @network_mutex = Mutex.new
+
+      @client.subscribe(@session_id) { |method, params| dispatch_event(method, params) }
+    end
+
+    # Navigate to `url` and block until the page's load event fires. Aliased as
+    # `go_to`.
+    #
+    # @param url [String] the URL to navigate to.
+    # @return [self]
+    def goto(url)
+      @load_queue = Queue.new
+      command("Page.navigate", url: url)
+      wait_for_load
+      self
+    end
+    alias_method :go_to, :goto
+
+    # Close this page's target and stop listening for its events.
+    #
+    # @return [Obxcura::Page, nil] the page, removed from the browser.
+    def close
+      @client.unsubscribe(@session_id)
+      @client.command("Network.clearBrowserCookies", { targetId: @target_id })
+      @client.command("Target.closeTarget", { targetId: @target_id })
+    rescue ProtocolError
+      # Target already gone — nothing to do.
+    ensure
+      @browser.remove_page(self)
+    end
+
+    # Drop the underlying WebSocket connection (affects the whole browser).
+    #
+    # @return [void]
+    def close_connection
+      @client.close
+    end
+
+    # Reload the page and block until it loads again. Aliased as `reload`.
+    #
+    # @return [Hash] the CDP `Page.reload` result.
+    def refresh
+      command("Page.reload")
+      wait_for_load
+    end
+    alias_method :reload, :refresh
+
+    # @return [Array<Hash>] the page's cookies as CDP cookie hashes.
+    def cookies
+      command("Storage.getCookies")["cookies"]
+    end
+
+    # Send a CDP command scoped to this page's session.
+    #
+    # @param method [String] the CDP method name.
+    # @param params [Hash] the method parameters.
+    # @return [Hash] the command's `result` object.
+    def command(method, params = {})
+      @client.command(method, params, session_id: @session_id)
+    end
+
+    # POST via XMLHttpRequest from the page context. Obscura routes XHR but not
+    # fetch, so this is the reliable POST path. All values cross as arguments,
+    # never interpolated into the JS. Returns { status, ok, body } on any HTTP
+    # reply (including 4xx/5xx). A transport failure — the request never reached
+    # the server (blocked by CORS / private-network SSRF guard, mixed origin, or
+    # a dead host) — raises ConnectionError instead of silently returning nil.
+    #
+    # `timeout` (seconds) bounds how long we wait for the reply. If the server
+    # accepts the connection but never answers the XHR (some anti-bot endpoints
+    # tarpit non-stealth clients), the wait ends with a TimeoutError that points
+    # at the likely cause. Note: Obscura ignores XMLHttpRequest#timeout, so the
+    # effective bound is this CDP-level one.
+    #
+    # @param url [String] the URL to POST to.
+    # @param payload [String] the raw request body.
+    # @param content_type [String] the Content-Type header value.
+    # @param headers [Hash{String=>String}] extra request headers.
+    # @param timeout [Integer, nil] seconds to wait for the reply.
+    # @return [Hash] `{ "status" => Integer, "ok" => Boolean, "body" => String }`.
+    # @raise [Obxcura::ConnectionError] if the request never reached the server.
+    # @raise [Obxcura::TimeoutError] if the server accepts but never answers.
+    def xhr_post(url, payload, content_type, headers, timeout: nil)
+      result = evaluate_func(<<~JS, url, payload, content_type, headers, timeout:)
+        function(url, payload, contentType, headers) {
+          return new Promise((resolve) => {
+            const x = new XMLHttpRequest();
+            x.onreadystatechange = () => {
+              if (x.readyState === 4) {
+                resolve({ status: x.status, ok: x.status >= 200 && x.status < 300, body: x.responseText });
+              }
+            };
+            x.onerror = () => resolve({ error: "network error or request blocked (CORS / private network / mixed origin)" });
+            try {
+              x.open("POST", url, true);
+              x.setRequestHeader("Content-Type", contentType);
+              Object.keys(headers).forEach((k) => x.setRequestHeader(k, headers[k]));
+              x.send(payload);
+            } catch (e) {
+              resolve({ error: String(e) });
+            }
+          });
+        }
+      JS
+
+      if result.nil? || result["error"]
+        reason = result&.dig("error") || "no response (request blocked or never settled)"
+        raise ConnectionError, "POST #{url} failed: #{reason}"
+      end
+
+      result
+    rescue TimeoutError
+      raise TimeoutError,
+        "POST #{url} did not complete in time. The server accepted the connection " \
+        "but never answered the XHR — likely anti-bot tarpitting. Try submitting the " \
+        "real form with #type/#submit, run `obscura serve --stealth`, or pass a larger timeout:."
+    end
+
+    private
+
+    def dispatch_event(method, params)
+      case method
+      when "Page.loadEventFired"
+        @load_queue.push(true)
+      when "Network.responseReceived"
+        @network_mutex.synchronize do
+          @network_log << { url: params.dig("response", "url"), request_id: params["requestId"], finished: false }
+        end
+      when "Network.loadingFinished"
+        @network_mutex.synchronize do
+          entry = @network_log.find { |e| e[:request_id] == params["requestId"] }
+          entry[:finished] = true if entry
+        end
+      end
+    end
+
+    def wait_for_load
+      Timeout.timeout(Client::DEFAULT_TIMEOUT, TimeoutError, "Page load timed out") { @load_queue.pop }
+    end
+  end
+end

data/lib/obxcura/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Obxcura
+  # The gem's semantic version string.
+  #
+  # @return [String]
+  VERSION = "0.1.1"
+end

data/lib/obxcura.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Obxcura — a small Ruby API for driving an Obscura browser
+# (h4ckf0r0day/obscura) over the Chrome DevTools Protocol.
+#
+# Obscura speaks CDP over a WebSocket, just like headless Chrome. The shape is
+# simple: a Browser owns one connection, and each Page is a target with its own
+# attached session. One connection, many pages.
+#
+#   require "obxcura"
+#
+#   browser = Obxcura::Browser.new         # connects to a running `obscura serve`
+#   page    = browser.create_page
+#   page.goto("https://www.google.com")
+#   puts page.html                         # rendered DOM (post-JS)
+#   browser.quit
+#
+# Start the browser first (defaults to port 9222):
+#   obscura serve
+#
+# nokogiri is optional — only needed for page.dom / at_css / css.
+
+require "json"
+require "net/http"
+require "uri"
+require "timeout"
+
+require_relative "obxcura/version"
+
+# Top-level namespace for the gem: a small Ruby client that drives an Obscura
+# headless browser over the Chrome DevTools Protocol. See the file header above
+# for the big picture; start from {Obxcura.start} or {Obxcura::Browser}.
+module Obxcura
+  # Base class for every error the gem raises, so callers can rescue the whole
+  # family with `rescue Obxcura::Error`.
+  class Error < StandardError; end
+
+  # Raised when a CDP command (or the initial connect) does not answer in time.
+  class TimeoutError < Error; end
+
+  # Raised when Obscura returns a protocol-level error, or JS throws during evaluate.
+  class ProtocolError < Error; end
+
+  # Raised when the browser endpoint can't be reached at all (nothing listening, etc).
+  class ConnectionError < Error; end
+
+  # Connect to a running `obscura serve` and return a Browser.
+  #
+  # @param options [Hash] forwarded to {Obxcura::Browser#initialize}
+  #   (`:host`, `:port`, `:timeout`).
+  # @return [Obxcura::Browser] a connected browser.
+  # @raise [Obxcura::ConnectionError] if no browser is listening.
+  # @example
+  #   browser = Obxcura.start(port: 9222)
+  #   page    = browser.go_to("https://example.com")
+  #   browser.quit
+  def self.start(**options)
+    Browser.new(**options)
+  end
+end
+
+require_relative "obxcura/client"
+require_relative "obxcura/node"
+require_relative "obxcura/frame"
+require_relative "obxcura/browser"
+require_relative "obxcura/page"

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: obxcura
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- memoxmrdl
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: websocket-driver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails-omakase
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: High-level Browser/Page API for driving h4ckf0r0day/obscura via the Chrome
+  DevTools Protocol.
+email:
+- jmemox@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/obxcura.rb
+- lib/obxcura/browser.rb
+- lib/obxcura/client.rb
+- lib/obxcura/frame.rb
+- lib/obxcura/frame/dom.rb
+- lib/obxcura/frame/runtime.rb
+- lib/obxcura/node.rb
+- lib/obxcura/page.rb
+- lib/obxcura/version.rb
+homepage: https://github.com/consultasimple/obxcura
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/consultasimple/obxcura
+  source_code_uri: https://github.com/consultasimple/obxcura
+  changelog_uri: https://github.com/consultasimple/obxcura/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: A small Ruby client for the Obscura headless browser over CDP.
+test_files: []