browserctl 0.11.0 → 0.13.0

data/lib/browserctl/server/command_dispatcher.rb

@@ -2,6 +2,7 @@
 
 require_relative "snapshot_builder"
 require_relative "page_session"
+require_relative "handlers/error_payload"
 require_relative "handlers/page_lifecycle"
 require_relative "handlers/navigation"
 require_relative "handlers/observation"
@@ -10,15 +11,16 @@ require_relative "handlers/hitl"
 require_relative "handlers/devtools"
 require_relative "handlers/daemon_control"
 require_relative "handlers/storage"
-require_relative "handlers/session"
 require_relative "handlers/state"
 require_relative "handlers/interaction"
 require_relative "../detectors"
 require_relative "../policy"
+require_relative "../errors"
 require_relative "../replay/snapshot_diff"
 
 module Browserctl
   class CommandDispatcher
+    include Handlers::ErrorPayload
     include Handlers::PageLifecycle
     include Handlers::Navigation
     include Handlers::Observation
@@ -27,7 +29,6 @@ module Browserctl
     include Handlers::DevTools
     include Handlers::DaemonControl
     include Handlers::Storage
-    include Handlers::Session
     include Handlers::State
     include Handlers::Interaction
 
@@ -67,10 +68,6 @@ module Browserctl
       "select" => :cmd_select,
       "dialog_accept" => :cmd_dialog_accept,
       "dialog_dismiss" => :cmd_dialog_dismiss,
-      "session_save" => :cmd_session_save,
-      "session_load" => :cmd_session_load,
-      "session_list" => :cmd_session_list,
-      "session_delete" => :cmd_session_delete,
       "state_save" => :cmd_state_save,
       "state_load" => :cmd_state_load,
       "state_list" => :cmd_state_list,
@@ -96,23 +93,38 @@ module Browserctl
     # @param req [Hash{Symbol => Object}] parsed request; must include `:cmd`
     # @return [Hash{Symbol => Object}] response; always includes `:ok` or `:error`
     def dispatch(req)
-      handler = COMMAND_MAP[req[:cmd]]
-      if handler
-        Browserctl.logger.debug("#{req[:cmd]} #{req[:name]}")
-        return send(handler, req)
-      end
+      builtin = dispatch_builtin(req)
+      return builtin if builtin
 
-      if (plugin = Browserctl.lookup_plugin_command(req[:cmd]))
-        Browserctl.logger.debug("plugin:#{req[:cmd]} #{req[:name]}")
-        session = req[:name] ? @global_mutex.synchronize { @pages[req[:name]] } : nil
-        return plugin.call(session, req)
-      end
+      plugin = dispatch_plugin(req)
+      return plugin if plugin
 
       { error: "unknown command: #{req[:cmd]}" }
     end
 
     private
 
+    # Routes the request to a builtin handler if `req[:cmd]` is in COMMAND_MAP.
+    # Returns the handler response, or `nil` if the command isn't a builtin.
+    def dispatch_builtin(req)
+      handler = COMMAND_MAP[req[:cmd]]
+      return nil unless handler
+
+      Browserctl.logger.debug("#{req[:cmd]} #{req[:name]}")
+      send(handler, req)
+    end
+
+    # Routes the request to a registered plugin command if one matches.
+    # Returns the plugin response, or `nil` if no plugin handles `req[:cmd]`.
+    def dispatch_plugin(req)
+      plugin = Browserctl.lookup_plugin_command(req[:cmd])
+      return nil unless plugin
+
+      Browserctl.logger.debug("plugin:#{req[:cmd]} #{req[:name]}")
+      session = req[:name] ? @global_mutex.synchronize { @pages[req[:name]] } : nil
+      plugin.call(session, req)
+    end
+
     def with_page(name)
       session = @global_mutex.synchronize { @pages[name] }
       return { error: "no page named '#{name}'" } unless session

data/lib/browserctl/server/handlers/daemon_control.rb

@@ -21,7 +21,11 @@ module Browserctl
         def cmd_fetch(req)
           key = req[:key].to_s
           found = @kv_mutex.synchronize { @kv_store.key?(key) ? { ok: true, value: @kv_store[key] } : nil }
-          found || { error: "key '#{key}' not found", code: "key_not_found" }
+          found || error_payload(
+            code: Browserctl::Error::Codes::KEY_NOT_FOUND,
+            message: "key '#{key}' not found",
+            context: { key: key }
+          )
         end
       end
     end

data/lib/browserctl/server/handlers/error_payload.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../../errors"
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      # Centralised structured-error builder for daemon JSON-RPC responses.
+      # Each handler returns `{ error:, code:, context:, suggested_action: }`
+      # for any failure carrying a stable {Browserctl::Error::Codes} code.
+      module ErrorPayload
+        # @param code [String] a SCREAMING_SNAKE code from {Codes}
+        # @param message [String] human-readable error
+        # @param context [Hash] free-form structured fields (selector, path, ...)
+        # @return [Hash{Symbol => Object}]
+        def error_payload(code:, message:, context: {})
+          {
+            error: message,
+            code: code,
+            context: context,
+            suggested_action: Browserctl::Error::SuggestedActions.for(code)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/server/handlers/interaction.rb

@@ -27,7 +27,13 @@ module Browserctl
               "return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; " \
               "})(#{sel.to_json})"
             )
-            return { error: "selector not found: #{sel}", code: "selector_not_found" } unless coords
+            unless coords
+              return error_payload(
+                code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+                message: "selector not found: #{sel}",
+                context: { selector: sel }
+              )
+            end
 
             session.page.mouse.move(x: coords["x"], y: coords["y"])
             { ok: true }
@@ -43,7 +49,13 @@ module Browserctl
             return sel if sel.is_a?(Hash)
 
             el = session.page.at_css(sel)
-            return { error: "selector not found: #{sel}", code: "selector_not_found" } unless el
+            unless el
+              return error_payload(
+                code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+                message: "selector not found: #{sel}",
+                context: { selector: sel }
+              )
+            end
 
             el.select_file(path)
             { ok: true }
@@ -56,7 +68,13 @@ module Browserctl
             return sel if sel.is_a?(Hash)
 
             el = session.page.at_css(sel)
-            return { error: "selector not found: #{sel}", code: "selector_not_found" } unless el
+            unless el
+              return error_payload(
+                code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+                message: "selector not found: #{sel}",
+                context: { selector: sel }
+              )
+            end
 
             el.evaluate(
               "this.value = #{req[:value].to_json}; " \

data/lib/browserctl/server/handlers/navigation.rb

@@ -8,7 +8,11 @@ module Browserctl
 
         def cmd_navigate(req)
           unless Policy.allowed_navigation?(req[:url].to_s)
-            return { error: "navigation to '#{req[:url]}' blocked by domain policy", code: "domain_not_allowed" }
+            return error_payload(
+              code: Browserctl::Error::Codes::DOMAIN_NOT_ALLOWED,
+              message: "navigation to '#{req[:url]}' blocked by domain policy",
+              context: { url: req[:url].to_s }
+            )
           end
 
           with_page(req[:name]) do |session|
@@ -81,7 +85,13 @@ module Browserctl
 
         def type_into(page, selector, value)
           el = page.at_css(selector)
-          return { error: "selector not found: #{selector}", code: "selector_not_found" } unless el
+          unless el
+            return error_payload(
+              code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+              message: "selector not found: #{selector}",
+              context: { selector: selector }
+            )
+          end
 
           el.focus
           el.evaluate("this.select()")
@@ -91,7 +101,13 @@ module Browserctl
 
         def click_element(page, selector)
           el = page.at_css(selector)
-          return { error: "selector not found: #{selector}", code: "selector_not_found" } unless el
+          unless el
+            return error_payload(
+              code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+              message: "selector not found: #{selector}",
+              context: { selector: selector }
+            )
+          end
 
           # Use the DOM native click() so JS-only event listeners fire.
           # CDP mouse simulation (el.click) dispatches events at screen coordinates

data/lib/browserctl/server/handlers/state.rb

@@ -15,21 +15,23 @@ module Browserctl
           first_session = @global_mutex.synchronize { @pages.values.first }
           return { error: "no open pages — open a page before saving state" } unless first_session
 
-          payload, captured_origins = capture_state_payload
-          manifest = Browserctl::State.save(
-            req[:name],
-            payload: payload,
+          captured, captured_origins = capture_state_payload
+          payload = Browserctl::State::Payload.build(
+            cookies: captured[:cookies],
+            local_storage: captured[:local_storage],
+            session_storage: captured[:session_storage],
             origins: req[:origins] || captured_origins,
             flow: req[:flow],
             flow_version: req[:flow_version],
             passphrase: req[:passphrase]
           )
+          manifest = Browserctl::State.save(req[:name], payload)
 
           {
             ok: true,
             path: Browserctl::State.path(req[:name]),
             origins: manifest[:origins],
-            cookies: payload[:cookies].length,
+            cookies: payload.cookies.length,
             encrypted: manifest[:encrypted]
           }
         rescue Browserctl::Error, ArgumentError => e

data/lib/browserctl/server.rb

@@ -6,7 +6,8 @@ require "fileutils"
 require "timeout"
 require_relative "constants"
 require_relative "logger"
-require_relative "driver"
+require_relative "driver/cdp_page"
+require_relative "driver/cdp"
 require_relative "server/command_dispatcher"
 require_relative "server/idle_watcher"
 require_relative "server/page_session"

data/lib/browserctl/state/bundle.rb

@@ -2,12 +2,13 @@
 
 require "json"
 require "openssl"
-require "securerandom"
 require_relative "../errors"
+require_relative "../error/codes"
+require_relative "../encryption_service"
 
 module Browserctl
   module State
-    # Single-file portable codec for browserctl session state — the .bctl
+    # Single-file portable codec for browserctl persisted state — the .bctl
     # bundle. Wraps a plaintext manifest (origins, flow binding, timestamps)
     # alongside a payload of cookies + storage. The manifest is always
     # readable without a passphrase (so `state info` can show origins and
@@ -36,20 +37,30 @@ module Browserctl
     #   first 32 bytes are the AES-256-GCM encryption key, last 32 bytes are
     #   the HMAC-SHA-256 key.
     #
-    # Reuses the same AES-256-GCM primitive as v0.8 session encryption
-    # (lib/browserctl/session.rb). The two will share a Crypto module in a
-    # follow-up; duplicated here to keep this PR focused.
+    # AES-256-GCM cipher setup and PBKDF2 key derivation are delegated to
+    # `Browserctl::EncryptionService` so this class stays focused on the
+    # bundle wire format. The service translates `OpenSSL::Cipher` errors
+    # into `EncryptionService::DecryptionError`, which we map to
+    # `PassphraseError` for the public API.
     class Bundle
       MAGIC          = "BCTL\x00".b.freeze
       VERSION        = 1
+      # Manifest-level format version, written as `format_version` and
+      # validated on decode. Distinct from the wire-format byte `VERSION`
+      # above (which gates the binary envelope shape) — this gates the
+      # manifest schema. See docs/reference/format-versions.md.
+      BUNDLE_FORMAT_VERSION = 1
+      SUPPORTED_FORMAT_VERSIONS = [BUNDLE_FORMAT_VERSION].freeze
       FLAG_ENCRYPTED = 0x01
       HEADER_SIZE    = MAGIC.bytesize + 3 # version + flags + reserved
       LEN_SIZE       = 4
       FOOTER_SIZE    = 32
-      SALT_SIZE      = 16
-      NONCE_SIZE     = 12
-      TAG_SIZE       = 16
-      PBKDF2_ITERS   = 200_000
+      # Cryptographic primitive sizes are sourced from EncryptionService so
+      # there is exactly one source of truth for cipher parameters.
+      SALT_SIZE      = Browserctl::EncryptionService::SALT_SIZE
+      NONCE_SIZE     = Browserctl::EncryptionService::NONCE_SIZE
+      TAG_SIZE       = Browserctl::EncryptionService::TAG_SIZE
+      PBKDF2_ITERS   = Browserctl::EncryptionService::PBKDF2_ITERS
 
       class BundleError      < Browserctl::Error; def self.default_code = "bundle_error"      end
       class TamperError      < BundleError;       def self.default_code = "bundle_tampered"   end
@@ -63,15 +74,16 @@ module Browserctl
       #   the footer is an HMAC. When nil, payload is plaintext and the
       #   footer is a SHA-256 digest.
       def self.encode(manifest:, payload:, passphrase: nil)
+        manifest = stamp_format_version(manifest)
         manifest_bytes = JSON.generate(manifest).b
         payload_json   = JSON.generate(payload).b
         flags          = 0
         hmac_key       = nil
 
         if passphrase
-          salt = SecureRandom.bytes(SALT_SIZE)
-          enc_key, hmac_key = derive_keys(passphrase, salt)
-          payload_bytes = salt + aes_gcm_encrypt(payload_json, enc_key)
+          salt = EncryptionService.random_salt
+          enc_key, hmac_key = EncryptionService.derive_keys(passphrase, salt)
+          payload_bytes = salt + EncryptionService.encrypt(payload_json, enc_key)
           flags |= FLAG_ENCRYPTED
         else
           payload_bytes = payload_json
@@ -96,7 +108,8 @@ module Browserctl
         verify_footer!(body, footer, encrypted: encrypted, passphrase: passphrase)
 
         manifest = JSON.parse(manifest_bytes, symbolize_names: true)
-        payload  = decode_payload(payload_bytes, encrypted: encrypted, passphrase: passphrase)
+        verify_format_version!(manifest)
+        payload = decode_payload(payload_bytes, encrypted: encrypted, passphrase: passphrase)
 
         { manifest: manifest, payload: payload, magic: magic, version: version, encrypted: encrypted }
       end
@@ -108,8 +121,40 @@ module Browserctl
         raise BundleError, "unsupported bundle version #{version}" unless version == VERSION
 
         manifest_bytes, = read_sections!(blob)
-        JSON.parse(manifest_bytes, symbolize_names: true)
+        manifest = JSON.parse(manifest_bytes, symbolize_names: true)
+        verify_format_version!(manifest)
+        manifest
+      end
+
+      # Returns the manifest with `format_version` set as the first key. When
+      # the caller already provided a value we keep it (so encoders can stamp
+      # a future version explicitly); otherwise we stamp the current one.
+      def self.stamp_format_version(manifest)
+        existing = manifest[:format_version] || manifest["format_version"]
+        version = existing || BUNDLE_FORMAT_VERSION
+        rest = manifest.except(:format_version, "format_version")
+        { format_version: version }.merge(rest)
+      end
+      private_class_method :stamp_format_version
+
+      # Raises Browserctl::ProtocolMismatch when the manifest declares no
+      # format_version or one this build does not support. The error carries
+      # the canonical PROTOCOL_MISMATCH code from the v0.12 error taxonomy.
+      def self.verify_format_version!(manifest, path: nil)
+        version = manifest[:format_version] || manifest["format_version"]
+        return if version && SUPPORTED_FORMAT_VERSIONS.include?(version)
+
+        where = path ? " at #{path}" : ""
+        msg = if version.nil?
+                "bundle manifest#{where} is missing format_version " \
+                  "(supported: #{SUPPORTED_FORMAT_VERSIONS.inspect})"
+              else
+                "bundle manifest#{where} declares format_version=#{version.inspect}, " \
+                  "this build supports #{SUPPORTED_FORMAT_VERSIONS.inspect}"
+              end
+        raise Browserctl::ProtocolMismatch.new(msg, code: Browserctl::Error::Codes::PROTOCOL_MISMATCH)
       end
+      private_class_method :verify_format_version!
 
       def self.build_body(flags, manifest_bytes, payload_bytes)
         header = MAGIC + [VERSION, flags, 0].pack("CCC")
@@ -166,7 +211,7 @@ module Browserctl
           # We need the HMAC key, which depends on the salt embedded in the
           # payload. Pull the salt from the payload bytes inside `body`.
           salt = extract_salt!(body)
-          _, hmac_key = derive_keys(passphrase, salt)
+          _, hmac_key = EncryptionService.derive_keys(passphrase, salt)
           expected = OpenSSL::HMAC.digest("SHA256", hmac_key, body)
           raise PassphraseError, "wrong passphrase or tampered bundle" unless secure_eq?(footer, expected)
         else
@@ -189,48 +234,17 @@ module Browserctl
         if encrypted
           salt       = bytes.byteslice(0, SALT_SIZE)
           ciphertext = bytes.byteslice(SALT_SIZE, bytes.bytesize - SALT_SIZE)
-          enc_key, = derive_keys(passphrase, salt)
-          plaintext  = aes_gcm_decrypt(ciphertext, enc_key)
+          enc_key, = EncryptionService.derive_keys(passphrase, salt)
+          plaintext  = EncryptionService.decrypt(ciphertext, enc_key)
           JSON.parse(plaintext)
         else
           JSON.parse(bytes)
         end
-      rescue OpenSSL::Cipher::CipherError
+      rescue EncryptionService::DecryptionError
         raise PassphraseError, "wrong passphrase — payload could not be decrypted"
       end
       private_class_method :decode_payload
 
-      def self.derive_keys(passphrase, salt)
-        material = OpenSSL::PKCS5.pbkdf2_hmac(passphrase.to_s, salt, PBKDF2_ITERS, 64, "SHA256")
-        [material.byteslice(0, 32), material.byteslice(32, 32)]
-      end
-      private_class_method :derive_keys
-
-      def self.aes_gcm_encrypt(plaintext, key)
-        cipher = OpenSSL::Cipher.new("aes-256-gcm")
-        cipher.encrypt
-        cipher.key = key
-        nonce = SecureRandom.bytes(NONCE_SIZE)
-        cipher.iv = nonce
-        ct = cipher.update(plaintext) + cipher.final
-        nonce + ct + cipher.auth_tag
-      end
-      private_class_method :aes_gcm_encrypt
-
-      def self.aes_gcm_decrypt(blob, key)
-        nonce      = blob.byteslice(0, NONCE_SIZE)
-        tag        = blob.byteslice(-TAG_SIZE, TAG_SIZE)
-        ciphertext = blob.byteslice(NONCE_SIZE, blob.bytesize - NONCE_SIZE - TAG_SIZE)
-
-        cipher = OpenSSL::Cipher.new("aes-256-gcm")
-        cipher.decrypt
-        cipher.key      = key
-        cipher.iv       = nonce
-        cipher.auth_tag = tag
-        cipher.update(ciphertext) + cipher.final
-      end
-      private_class_method :aes_gcm_decrypt
-
       def self.secure_eq?(actual, expected)
         return false if actual.bytesize != expected.bytesize
 

data/lib/browserctl/state.rb

@@ -42,6 +42,41 @@ module Browserctl
     EXTENSION = ".bctl"
     MANIFEST_VERSION = 1
 
+    # Value object bundling everything needed to persist a state bundle. The
+    # browser-side data lives in `cookies`, `local_storage`, and
+    # `session_storage`; the manifest extras live in `origins`, `flow`, and
+    # `flow_version`; `passphrase` flips the bundle into an encrypted variant.
+    Payload = Data.define(
+      :cookies,
+      :local_storage,
+      :session_storage,
+      :origins,
+      :flow,
+      :flow_version,
+      :passphrase
+    ) do
+      def self.build(cookies: [], local_storage: {}, session_storage: {}, # rubocop:disable Metrics/ParameterLists
+                     origins: nil, flow: nil, flow_version: nil, passphrase: nil)
+        new(
+          cookies: cookies,
+          local_storage: local_storage,
+          session_storage: session_storage,
+          origins: origins,
+          flow: flow,
+          flow_version: flow_version,
+          passphrase: passphrase
+        )
+      end
+
+      def to_bundle_payload
+        {
+          cookies: cookies,
+          local_storage: local_storage,
+          session_storage: session_storage
+        }
+      end
+    end
+
     def self.path(name) = File.join(BASE_DIR, "#{name}#{EXTENSION}")
     def self.exist?(name) = File.exist?(path(name))
 
@@ -51,22 +86,24 @@ module Browserctl
       raise ArgumentError, "invalid state name #{name.inspect} — use letters, digits, _ or - (max 64 chars)"
     end
 
-    # Persist a bundle. `payload` is { cookies:, local_storage:, session_storage: }.
-    # `manifest_extras` may carry origins (override), flow, flow_version.
-    def self.save(name, payload:, origins: nil, flow: nil, flow_version: nil, passphrase: nil) # rubocop:disable Metrics/ParameterLists
+    # Persist a bundle. `payload` is a `State::Payload` value object carrying
+    # cookies, local/session storage, and the manifest extras (origins, flow,
+    # flow_version, passphrase).
+    def self.save(name, payload)
       validate_name!(name)
       FileUtils.mkdir_p(BASE_DIR)
 
+      bundle_payload = payload.to_bundle_payload
       manifest = build_manifest(
         name: name,
-        origins: origins || derive_origins(payload),
-        flow: flow,
-        flow_version: flow_version,
-        cookies: payload[:cookies] || payload["cookies"] || [],
-        encrypted: !passphrase.nil?
+        origins: payload.origins || derive_origins(bundle_payload),
+        flow: payload.flow,
+        flow_version: payload.flow_version,
+        cookies: payload.cookies || [],
+        encrypted: !payload.passphrase.nil?
       )
 
-      blob = Bundle.encode(manifest: manifest, payload: payload, passphrase: passphrase)
+      blob = Bundle.encode(manifest: manifest, payload: bundle_payload, passphrase: payload.passphrase)
       File.open(path(name), "wb", 0o600) { |f| f.write(blob) }
       manifest
     end

data/lib/browserctl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Browserctl
-  VERSION = "0.11.0"
+  VERSION = "0.13.0"
 end

data/lib/browserctl/workflow/flow_wrapper.rb

@@ -59,7 +59,7 @@ module Browserctl
       def write(defn, overwrite: true, dir: nil)
         path = dir ? File.join(dir, "#{defn.name}.rb") : target_path(defn.name)
         if File.exist?(path) && !overwrite
-          raise "flow wrapper already exists at #{path} (pass overwrite: true to replace)"
+          raise Browserctl::WorkflowError, "flow wrapper already exists at #{path} (pass overwrite: true to replace)"
         end
 
         FileUtils.mkdir_p(File.dirname(path))

data/lib/browserctl/workflow/recovery_manager.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Workflow
+    # Owns the AUTH_REQUIRED recovery state machine for `load_state`.
+    #
+    # When the daemon reports AUTH_REQUIRED on a `state_load` (e.g. expired
+    # cookies in the bundle), the manager either runs the bound flow or
+    # the caller-provided override, re-saves the bundle, and reloads it
+    # with `skip_auth_check: true`.
+    #
+    # Decoupled from {ContextualPersistence} so the multi-step recovery
+    # logic has a dedicated home and a dedicated spec. The host context
+    # only needs to expose `client` (for daemon RPCs) and `invoke` (for
+    # running the bound flow); see {ContextualPersistence#load_state}.
+    class RecoveryManager
+      AUTH_REQUIRED_CODE = "AUTH_REQUIRED"
+
+      # @param context [#client, #invoke] a workflow context exposing
+      #   the daemon client and an `invoke(flow_name, page:)` entry point.
+      def initialize(context)
+        @context = context
+      end
+
+      # True when `res` is the daemon's AUTH_REQUIRED preflight signal.
+      def self.auth_required?(res)
+        (res[:code] || res["code"]) == AUTH_REQUIRED_CODE
+      end
+
+      # Run recovery for `state_name` given the daemon's initial AUTH_REQUIRED
+      # response. Returns the merged retry result (with `rotated: true`) or
+      # raises {WorkflowError} when no flow is bound and no override is
+      # supplied, or when the post-rotation reload still fails.
+      #
+      # @param state_name      [String]  the bundle name being loaded
+      # @param initial_res     [Hash]    the original AUTH_REQUIRED response
+      # @param on_auth_required [Proc, nil] optional override; when given,
+      #   it runs in lieu of invoking the suggested flow.
+      def recover(state_name, initial_res, on_auth_required: nil)
+        if on_auth_required
+          on_auth_required.call
+        else
+          invoke_bound_flow(state_name, initial_res)
+        end
+
+        rotate_and_reload(state_name)
+      end
+
+      private
+
+      attr_reader :context
+
+      def invoke_bound_flow(state_name, initial_res)
+        flow_name = initial_res[:suggested_flow] || initial_res["suggested_flow"]
+        if flow_name.nil? || flow_name.to_s.empty?
+          raise WorkflowError,
+                "state '#{state_name}' needs auth but bundle has no bound flow — " \
+                "save with `save_state('#{state_name}', flow: :NAME)` or pass on_auth_required:"
+        end
+
+        # Match the daemon's `state load` preflight: it auth-checks the first
+        # open page (insertion order). Passing that same name to the flow
+        # gives stdlib flows a `page` proxy to drive (oauth_github reads
+        # `page.url`, totp_2fa calls `page.fill`, etc.). Falls back to no
+        # page only when nothing is open — `state_save` would have errored
+        # earlier in that case, so this is a defence-in-depth nil.
+        context.invoke(flow_name, page: first_open_page)
+      end
+
+      def rotate_and_reload(state_name)
+        after_save = context.client.state_save(state_name)
+        raise WorkflowError, after_save[:error] if after_save[:error]
+
+        retry_res = context.client.state_load(state_name, skip_auth_check: true)
+        raise WorkflowError, retry_res[:error] if retry_res[:error]
+
+        retry_res.merge(rotated: true)
+      end
+
+      def first_open_page
+        res = context.client.page_list
+        pages = res[:pages] || res["pages"] || []
+        pages.first
+      end
+    end
+  end
+end