browserctl 0.12.0 → 0.13.0

data/examples/session_reuse.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-# Demonstrates the authenticate-once, reuse-forever pattern.
-#
-# The first run (no saved session) invokes `login_once` to authenticate,
-# which saves the session. Every subsequent run loads the saved session
-# directly — no re-authentication needed.
-#
-# `expired_if:` detects when the saved session exists but server-side auth
-# has lapsed (rotated cookie, token TTL), and automatically re-authenticates.
-#
-# Run:
-#   browserctl workflow run examples/session_reuse.rb \
-#     --app_url https://the-internet.herokuapp.com \
-#     --username tomsmith \
-#     --password "SuperSecretPassword!"
-#
-# On the first run: authenticates and saves the session.
-# On subsequent runs: loads the session and skips the login page entirely.
-
-# --- Step 1: define the login workflow (run once, triggered automatically on missing/expired session) ---
-
-Browserctl.workflow "session_reuse/login_once" do
-  desc "Authenticate and save session — called automatically by session_reuse when needed"
-
-  param :app_url,  required: true
-  param :username, required: true
-  param :password, required: true, secret: true
-
-  step "open login page" do
-    open_page(:main, url: "#{app_url}/login")
-  end
-
-  step "fill and submit credentials" do
-    page(:main).fill("input#username", username)
-    page(:main).fill("input#password", password)
-    page(:main).click("button[type=submit]")
-  end
-
-  step "verify login succeeded" do
-    assert page(:main).url.include?("/secure"), "login failed — still on login page"
-  end
-
-  step "save authenticated session" do
-    save_session("session_reuse_demo")
-    puts "  ✓ Session saved — future runs will skip this step"
-  end
-end
-
-# --- Step 2: the main workflow that reuses the saved session ---
-
-Browserctl.workflow "session_reuse" do
-  desc "Authenticate once, reuse forever — demonstrates load_session with fallback and expired_if"
-
-  param :app_url,  default: "https://the-internet.herokuapp.com"
-  param :username, default: "tomsmith"
-  param :password, default: "SuperSecretPassword!", secret: true
-
-  step "restore session or log in" do
-    load_session("session_reuse_demo",
-                 fallback: "session_reuse/login_once",
-                 expired_if: lambda {
-                   page(:main).navigate("#{app_url}/secure")
-                   !page(:main).url.include?("/secure")
-                 })
-    puts "  ✓ Session ready — authenticated as #{username}"
-  end
-
-  step "do authenticated work" do
-    page(:main).navigate("#{app_url}/secure")
-    heading = page(:main).evaluate("document.querySelector('h2')?.textContent?.trim()")
-    assert heading&.include?("Secure Area"), "expected to be in secure area, got: #{heading.inspect}"
-    puts "  ✓ Landed in secure area without re-authenticating"
-  end
-end

data/lib/browserctl/commands/session.rb

@@ -1,243 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-require "io/console"
-require "json"
-require "open3"
-require "openssl"
-require "securerandom"
-require "tmpdir"
-require_relative "cli_output"
-
-module Browserctl
-  module Commands
-    module Session
-      extend CliOutput
-
-      USAGE = "Usage: browserctl session <save|load|list|delete|export|import> [args]"
-
-      PBKDF2_ITERATIONS = 100_000
-      PBKDF2_KEY_LEN    = 32
-      SALT_LEN          = 16
-      NONCE_LEN         = 12
-
-      SENSITIVE_BASENAMES = %w[cookies.json local_storage.json session_storage.json].freeze
-
-      def self.run(client, args)
-        sub = args.shift or abort USAGE
-        case sub
-        when "save"   then run_save(client, args)
-        when "load"   then run_load(client, args)
-        when "list"   then run_list(client)
-        when "delete" then run_delete(client, args)
-        when "export" then run_export(args)
-        when "import" then run_import(args)
-        else abort "unknown session subcommand '#{sub}'\n#{USAGE}"
-        end
-      end
-
-      def self.run_save(client, args)
-        encrypt = args.delete("--encrypt")
-        name    = args.shift or abort "usage: browserctl session save <name> [--encrypt]"
-        print_result(client.session_save(name, encrypt: !!encrypt))
-      end
-
-      def self.run_load(client, args)
-        name = args.shift or abort "usage: browserctl session load <name>"
-        print_result(client.session_load(name))
-      end
-
-      def self.run_list(client)
-        print_result(client.session_list)
-      end
-
-      def self.run_delete(client, args)
-        name = args.shift or abort "usage: browserctl session delete <name>"
-        print_result(client.session_delete(name))
-      end
-
-      def self.run_export(args)
-        encrypt = args.delete("--encrypt")
-        name    = args.shift or abort "usage: browserctl session export <name> <path> [--encrypt]"
-        dest    = args.shift or abort "usage: browserctl session export <name> <path> [--encrypt]"
-
-        Browserctl::Session.validate_name!(name)
-        session_dir = File.join(Browserctl::BROWSERCTL_DIR, "sessions", name)
-        abort "session '#{name}' not found" unless Dir.exist?(session_dir)
-
-        dest = File.expand_path(dest)
-
-        if encrypt
-          passphrase = prompt_passphrase(confirm: true)
-          encrypt_export(session_dir, name, dest, passphrase)
-        else
-          pid = Process.spawn("zip", "-r", dest, name, chdir: File.join(Browserctl::BROWSERCTL_DIR, "sessions"))
-          Process.wait(pid)
-        end
-
-        puts({ ok: true, path: dest }.to_json)
-      end
-
-      def self.run_import(args)
-        zip_path = args.shift or abort "usage: browserctl session import <path>"
-        zip_path = File.expand_path(zip_path)
-        abort "zip file not found: #{zip_path}" unless File.exist?(zip_path)
-
-        sessions_dir = File.join(Browserctl::BROWSERCTL_DIR, "sessions")
-        FileUtils.mkdir_p(sessions_dir)
-
-        before = Dir[File.join(sessions_dir, "*/")].map { |p| File.basename(p) }
-
-        if encrypted_zip?(zip_path)
-          passphrase = prompt_passphrase
-          decrypt_import(zip_path, sessions_dir, passphrase)
-        else
-          pid = Process.spawn("unzip", "-o", zip_path, "-d", sessions_dir)
-          Process.wait(pid)
-        end
-
-        after = Dir[File.join(sessions_dir, "*/")].map { |p| File.basename(p) }
-        name = (after - before).first
-
-        puts({ ok: true, name: name }.to_json)
-      end
-
-      # --- private helpers ---
-
-      def self.prompt_passphrase(confirm: false)
-        return ENV["BROWSERCTL_EXPORT_PASSPHRASE"] if ENV["BROWSERCTL_EXPORT_PASSPHRASE"]
-
-        $stderr.print "Passphrase: "
-        pass = $stdin.noecho(&:gets).to_s.chomp
-        $stderr.puts
-
-        if confirm
-          $stderr.print "Confirm passphrase: "
-          confirm_pass = $stdin.noecho(&:gets).to_s.chomp
-          $stderr.puts
-          abort "Passphrases do not match." unless pass == confirm_pass
-        end
-
-        pass
-      end
-      private_class_method :prompt_passphrase
-
-      def self.derive_key(passphrase, salt)
-        OpenSSL::PKCS5.pbkdf2_hmac(
-          passphrase,
-          salt,
-          PBKDF2_ITERATIONS,
-          PBKDF2_KEY_LEN,
-          OpenSSL::Digest.new("SHA256")
-        )
-      end
-      private_class_method :derive_key
-
-      def self.encrypt_blob(plaintext, key)
-        nonce  = SecureRandom.bytes(NONCE_LEN)
-        cipher = OpenSSL::Cipher.new("aes-256-gcm")
-        cipher.encrypt
-        cipher.key = key
-        cipher.iv  = nonce
-        ct  = cipher.update(plaintext) + cipher.final
-        tag = cipher.auth_tag
-        nonce + ct + tag
-      end
-      private_class_method :encrypt_blob
-
-      def self.decrypt_blob(blob, key)
-        nonce      = blob.byteslice(0, NONCE_LEN)
-        tag        = blob.byteslice(-16, 16)
-        ciphertext = blob.byteslice(NONCE_LEN, blob.bytesize - NONCE_LEN - 16)
-        cipher = OpenSSL::Cipher.new("aes-256-gcm")
-        cipher.decrypt
-        cipher.key      = key
-        cipher.iv       = nonce
-        cipher.auth_tag = tag
-        cipher.update(ciphertext) + cipher.final
-      rescue OpenSSL::Cipher::CipherError => e
-        raise Browserctl::Error, "export decryption failed: #{e.message}"
-      end
-      private_class_method :decrypt_blob
-
-      # Build an encrypted zip using the system zip command.
-      # Plaintext files are staged in a tmpdir; sensitive ones are encrypted
-      # before staging. An _encryption_manifest.json is added at the zip root.
-      def self.encrypt_export(session_dir, session_name, dest, passphrase)
-        salt = SecureRandom.bytes(SALT_LEN)
-        key  = derive_key(passphrase, salt)
-        manifest = JSON.generate({
-                                   encrypted: true, kdf: "pbkdf2-sha256",
-                                   iterations: PBKDF2_ITERATIONS, salt: salt.unpack1("H*")
-                                 })
-        Dir.mktmpdir do |tmpdir|
-          File.write(File.join(tmpdir, "_encryption_manifest.json"), manifest)
-          stage_session_files(session_dir, session_name, tmpdir, key)
-          pid = Process.spawn("zip", "-r", dest, "_encryption_manifest.json", session_name, chdir: tmpdir)
-          Process.wait(pid)
-        end
-      end
-      private_class_method :encrypt_export
-
-      def self.stage_session_files(session_dir, session_name, tmpdir, key)
-        staged_session = File.join(tmpdir, session_name)
-        FileUtils.mkdir_p(staged_session)
-        Dir[File.join(session_dir, "**", "*")].each do |file|
-          next if File.directory?(file)
-
-          relative    = file.delete_prefix("#{session_dir}/")
-          staged_path = File.join(staged_session, relative)
-          FileUtils.mkdir_p(File.dirname(staged_path))
-          raw = File.binread(file)
-          if SENSITIVE_BASENAMES.include?(File.basename(file))
-            File.binwrite("#{staged_path}.enc", encrypt_blob(raw, key))
-          else
-            File.binwrite(staged_path, raw)
-          end
-        end
-      end
-      private_class_method :stage_session_files
-
-      # Returns true if the zip contains _encryption_manifest.json.
-      def self.encrypted_zip?(zip_path)
-        out, status = Open3.capture2("unzip", "-l", zip_path)
-        status.success? && out.include?("_encryption_manifest.json")
-      end
-      private_class_method :encrypted_zip?
-
-      # Extract zip to tmpdir, read manifest, decrypt .enc files, copy to sessions_dir.
-      def self.decrypt_import(zip_path, sessions_dir, passphrase)
-        Dir.mktmpdir do |tmpdir|
-          pid = Process.spawn("unzip", "-o", zip_path, "-d", tmpdir)
-          Process.wait(pid)
-          manifest_path = File.join(tmpdir, "_encryption_manifest.json")
-          raise Browserctl::Error, "missing encryption manifest in zip" unless File.exist?(manifest_path)
-
-          manifest = JSON.parse(File.read(manifest_path), symbolize_names: true)
-          key = derive_key(passphrase, [manifest[:salt]].pack("H*"))
-          copy_decrypted_files(tmpdir, sessions_dir, key)
-        end
-      end
-      private_class_method :decrypt_import
-
-      def self.copy_decrypted_files(tmpdir, sessions_dir, key)
-        Dir[File.join(tmpdir, "**", "*")].each do |file|
-          next if File.directory?(file)
-          next if File.basename(file) == "_encryption_manifest.json"
-
-          relative  = file.delete_prefix("#{tmpdir}/")
-          dest_path = File.join(sessions_dir, relative)
-          FileUtils.mkdir_p(File.dirname(dest_path))
-          if file.end_with?(".enc")
-            File.open(dest_path.delete_suffix(".enc"), "wb", 0o600) do |f|
-              f.write(decrypt_blob(File.binread(file), key))
-            end
-          else
-            FileUtils.cp(file, dest_path)
-          end
-        end
-      end
-      private_class_method :copy_decrypted_files
-    end
-  end
-end

data/lib/browserctl/driver/base.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module Browserctl
-  module Driver
-    class Base
-      def create_page   = raise NotImplementedError, "#{self.class.name}#create_page not implemented"
-      def quit          = raise NotImplementedError, "#{self.class.name}#quit not implemented"
-      def headed?       = raise NotImplementedError, "#{self.class.name}#headed? not implemented"
-      def supports?(_)  = false
-      def devtools_info(_page) = raise NotImplementedError, "#{self.class.name}#devtools_info not implemented"
-    end
-  end
-end

data/lib/browserctl/driver.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "driver/base"
-require_relative "driver/cdp_page"
-require_relative "driver/cdp"

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

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../session"
-
-module Browserctl
-  class CommandDispatcher
-    module Handlers
-      module Session
-        private
-
-        def cmd_session_save(req)
-          first_session = @global_mutex.synchronize { @pages.values.first }
-          return { error: "no open pages — open a page before saving a session" } unless first_session
-
-          cookies = first_session.page.cookies.all.values.map(&:to_h)
-
-          pages_meta    = {}
-          local_storage = {}
-          @global_mutex.synchronize { @pages.dup }.each do |page_name, session|
-            session.mutex.synchronize do
-              origin    = session.page.evaluate("location.origin")
-              local_str = session.page.evaluate("JSON.stringify({...localStorage})")
-              pages_meta[page_name] = { url: session.page.current_url, title: session.page.title }
-              local_storage[origin] = JSON.parse(local_str)
-            end
-          end
-
-          now = Time.now.iso8601
-          Browserctl::Session.save(
-            req[:session_name],
-            metadata: { version: 1, name: req[:session_name],
-                        created_at: now, updated_at: now, pages: pages_meta },
-            cookies: cookies,
-            local_storage: local_storage,
-            session_storage: {},
-            encrypt: req[:encrypt] || false
-          )
-          { ok: true, path: Browserctl::Session.path(req[:session_name]),
-            pages: pages_meta.length, cookies: cookies.length }
-        end
-
-        def cmd_session_load(req)
-          data = Browserctl::Session.load(req[:session_name])
-
-          data[:metadata][:pages].each do |page_name, page_data|
-            existing = @global_mutex.synchronize { @pages[page_name.to_s] }
-            if existing
-              existing.page.go_to(page_data[:url])
-            else
-              new_page = @driver.create_page
-              new_page.go_to(page_data[:url])
-              @global_mutex.synchronize { @pages[page_name.to_s] = PageSession.new(new_page) }
-            end
-          end
-
-          seed_session = @global_mutex.synchronize { @pages.values.first }
-          cookie_count = data[:cookies].length
-          data[:cookies].each { |c| seed_session.page.cookies.set(**c.slice(:name, :value, :domain, :path)) }
-
-          ls_key_count = 0
-          data[:local_storage].each do |origin, keys|
-            next if keys.empty?
-
-            tmp_page = @driver.create_page
-            begin
-              tmp_page.go_to(origin)
-              keys.each do |k, v|
-                tmp_page.evaluate("localStorage.setItem(#{k.to_json}, #{v.to_json})")
-                ls_key_count += 1
-              end
-            ensure
-              tmp_page.close
-            end
-          end
-
-          { ok: true, cookies: cookie_count, pages: data[:metadata][:pages].length,
-            local_storage_keys: ls_key_count }
-        rescue Browserctl::Error, ArgumentError, JSON::ParserError, RuntimeError => e
-          { error: e.message }
-        end
-
-        def cmd_session_list(_req)
-          sessions = Browserctl::Session.all
-          { ok: true, sessions: sessions }
-        end
-
-        def cmd_session_delete(req)
-          Browserctl::Session.delete(req[:session_name])
-          { ok: true }
-        end
-      end
-    end
-  end
-end

data/lib/browserctl/session.rb

@@ -1,206 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-require "json"
-require "openssl"
-require "securerandom"
-require "open3"
-require_relative "constants"
-
-module Browserctl
-  class Session
-    BASE_DIR = File.join(BROWSERCTL_DIR, "sessions")
-
-    SAFE_NAME = /\A[a-zA-Z0-9_-]{1,64}\z/
-
-    SENSITIVE_FILES = %w[cookies.json local_storage.json session_storage.json].freeze
-
-    def self.path(name)    = File.join(BASE_DIR, name)
-    def self.exist?(name)  = Dir.exist?(path(name))
-
-    def self.delete(name)
-      validate_name!(name)
-      FileUtils.rm_rf(path(name))
-    end
-
-    def self.all
-      Dir[File.join(BASE_DIR, "*/metadata.json")].filter_map { |f| load_meta(f) }
-    end
-
-    def self.save(session_name, metadata:, cookies:, local_storage:, session_storage:, encrypt: false) # rubocop:disable Metrics/ParameterLists
-      validate_name!(session_name)
-      key, metadata = prepare_encryption(session_name, metadata, encrypt)
-      dir = path(session_name)
-      FileUtils.mkdir_p(dir)
-      write_json(File.join(dir, "metadata.json"), metadata)
-      write_session_files(dir, cookies, local_storage, session_storage, key)
-    end
-
-    def self.prepare_encryption(session_name, metadata, encrypt)
-      return [nil, metadata] unless encrypt
-
-      unless keychain_available?
-        raise Browserctl::Error,
-              "session encryption requires macOS Keychain (darwin only)\n  " \
-              "For Linux/CI, omit --encrypt and rely on 0o600 file permissions,\n  " \
-              "or use BROWSERCTL_EXPORT_PASSPHRASE with session export --encrypt for portable archives."
-      end
-
-      key = SecureRandom.bytes(32)
-      keychain_store(session_name, key)
-      [key, metadata.merge(encrypted: true)]
-    end
-    private_class_method :prepare_encryption
-
-    def self.write_session_files(dir, cookies, local_storage, session_storage, key)
-      if key
-        write_encrypted_secret(File.join(dir, "cookies.json.enc"), cookies, key)
-        write_encrypted_secret(File.join(dir, "local_storage.json.enc"), local_storage, key)
-        unless session_storage.empty?
-          write_encrypted_secret(File.join(dir, "session_storage.json.enc"), session_storage,
-                                 key)
-        end
-      else
-        write_secret(File.join(dir, "cookies.json"), cookies)
-        write_secret(File.join(dir, "local_storage.json"), local_storage)
-        write_secret(File.join(dir, "session_storage.json"), session_storage) unless session_storage.empty?
-      end
-    end
-    private_class_method :write_session_files
-
-    def self.load(session_name)
-      validate_name!(session_name)
-      dir = path(session_name)
-      raise Browserctl::Error, "session '#{session_name}' not found" unless Dir.exist?(dir)
-
-      meta = JSON.parse(File.read(File.join(dir, "metadata.json")), symbolize_names: true)
-
-      if meta[:encrypted]
-        key = keychain_fetch(session_name)
-        {
-          metadata: meta,
-          cookies: decrypt_json(File.join(dir, "cookies.json.enc"), key, symbolize_names: true),
-          local_storage: decrypt_json(File.join(dir, "local_storage.json.enc"), key, symbolize_names: false),
-          session_storage: load_session_storage_encrypted(dir, key)
-        }
-      else
-        {
-          metadata: meta,
-          cookies: JSON.parse(File.read(File.join(dir, "cookies.json")), symbolize_names: true),
-          local_storage: JSON.parse(File.read(File.join(dir, "local_storage.json")), symbolize_names: false),
-          session_storage: load_session_storage(dir)
-        }
-      end
-    end
-
-    def self.load_meta(path)
-      JSON.parse(File.read(path), symbolize_names: true)
-    rescue JSON::ParserError
-      nil
-    end
-
-    def self.validate_name!(name)
-      return if SAFE_NAME.match?(name.to_s)
-
-      raise ArgumentError, "invalid session name #{name.inspect} — use letters, digits, _ or - (max 64 chars)"
-    end
-
-    # Encrypt data (JSON) and return binary blob: [12-byte nonce][ciphertext+16-byte tag]
-    def self.encrypt_file(data, key)
-      nonce = SecureRandom.bytes(12)
-      cipher = OpenSSL::Cipher.new("aes-256-gcm")
-      cipher.encrypt
-      cipher.key = key
-      cipher.iv  = nonce
-      ciphertext = cipher.update(data) + cipher.final
-      tag        = cipher.auth_tag
-      nonce + ciphertext + tag
-    end
-    private_class_method :encrypt_file
-
-    # Decrypt binary blob produced by encrypt_file; returns original plaintext string.
-    def self.decrypt_file(blob, key)
-      nonce      = blob.byteslice(0, 12)
-      tag        = blob.byteslice(-16, 16)
-      ciphertext = blob.byteslice(12, blob.bytesize - 28)
-
-      cipher = OpenSSL::Cipher.new("aes-256-gcm")
-      cipher.decrypt
-      cipher.key      = key
-      cipher.iv       = nonce
-      cipher.auth_tag = tag
-      cipher.update(ciphertext) + cipher.final
-    rescue OpenSSL::Cipher::CipherError => e
-      raise Browserctl::Error, "decryption failed: #{e.message}"
-    end
-    private_class_method :decrypt_file
-
-    def self.keychain_store(name, key)
-      hex_key = key.unpack1("H*")
-      out, status = Open3.capture2(
-        "security", "add-generic-password",
-        "-a", name,
-        "-s", "browserctl",
-        "-w", hex_key,
-        "-U"
-      )
-      raise Browserctl::Error, "keychain store failed: #{out}" unless status.success?
-    end
-    private_class_method :keychain_store
-
-    def self.keychain_fetch(name)
-      hex_key, status = Open3.capture2(
-        "security", "find-generic-password",
-        "-a", name,
-        "-s", "browserctl",
-        "-w"
-      )
-      raise Browserctl::Error, "keychain fetch failed for session '#{name}'" unless status.success?
-
-      [hex_key.strip].pack("H*")
-    end
-    private_class_method :keychain_fetch
-
-    def self.keychain_available?
-      RUBY_PLATFORM.include?("darwin") && system("which", "security", out: File::NULL, err: File::NULL)
-    end
-    private_class_method :keychain_available?
-
-    def self.load_session_storage(dir)
-      ss_path = File.join(dir, "session_storage.json")
-      File.exist?(ss_path) ? JSON.parse(File.read(ss_path), symbolize_names: false) : {}
-    end
-    private_class_method :load_session_storage
-
-    def self.load_session_storage_encrypted(dir, key)
-      ss_path = File.join(dir, "session_storage.json.enc")
-      return {} unless File.exist?(ss_path)
-
-      decrypt_json(ss_path, key, symbolize_names: false)
-    end
-    private_class_method :load_session_storage_encrypted
-
-    def self.decrypt_json(path, key, symbolize_names:)
-      blob = File.binread(path)
-      JSON.parse(decrypt_file(blob, key), symbolize_names: symbolize_names)
-    end
-    private_class_method :decrypt_json
-
-    def self.write_json(path, data)
-      File.open(path, "w", 0o600) { |f| f.write(JSON.generate(data)) }
-    end
-    private_class_method :write_json
-
-    # Cookies and storage contain secrets — restrict to owner read/write only.
-    def self.write_secret(path, data)
-      File.open(path, "w", 0o600) { |f| f.write(JSON.generate(data)) }
-    end
-    private_class_method :write_secret
-
-    def self.write_encrypted_secret(path, data, key)
-      blob = encrypt_file(JSON.generate(data), key)
-      File.open(path, "wb", 0o600) { |f| f.write(blob) }
-    end
-    private_class_method :write_encrypted_secret
-  end
-end