browserctl 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2662c63f1ab585b29689e8e09ac2c8f7c3214539c440c51da82efc954fc0493
-  data.tar.gz: 3e8f6790cdb3a3a79382f68c3a1fb6235805e6acc96658270d06c4d91ee1098b
+  metadata.gz: e85e284d37a585d84857db9f02a93bc7d9aacbf5c026da8ab06559fdff121f16
+  data.tar.gz: 76dbe3a44dee51d1c520dc0bd4d282790309efab1ecc5567fcee585b064660f1
 SHA512:
-  metadata.gz: d729193bb86f061227588d46981d7fc5aaf98ef45956a4f4c5e59ca30c95f02f2a06d0d2e9227e671e0f6fb8a3ffcdd2ec4347cc20bd30bb40b2bef54f8b25c4
-  data.tar.gz: 48170f604f692e980da8956c41f74255e0f16c6a43a13f3ae090377550bc14967a632a8ac01ebe85c7cabde1ff4226638e92fd40329cde0bcb2539c0c4a5c69a
+  metadata.gz: e66d36468423be0212176d8d40df94c5e10ba3d5f23663041b502c0d481580f94f12f308deaffac18b25fef1cc0bd644dac110e4d98ce365574ef6aa53dc4784
+  data.tar.gz: b147ca301c15e728b9bf6e3682bcf975f7f105adadd77d62db9a6a68fa8a05cd73533562f198b0825abc99f45ee73c04cf50aa2205d840d0181f3b599e9f7093

data/CHANGELOG.md

@@ -10,6 +10,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.1](https://github.com/patrick204nqh/browserctl/compare/v0.8.0...v0.8.1) (2026-04-29)
+
+
+### Bug Fixes
+
+* fill test gaps and tighten DX for v0.8.1 encryption ([#59](https://github.com/patrick204nqh/browserctl/issues/59)) ([80ae8b3](https://github.com/patrick204nqh/browserctl/commit/80ae8b38620f182db02a971516cfb5295cfb4945))
+* session encryption at rest and passphrase-protected export ([#57](https://github.com/patrick204nqh/browserctl/issues/57)) ([e3185d9](https://github.com/patrick204nqh/browserctl/commit/e3185d95dad3dd373659ce3c1e5781d9a06ed7f1))
+
+## [0.8.0](https://github.com/patrick204nqh/browserctl/compare/v0.7.0...v0.8.0) (2026-04-29)
+
+
+### Features
+
+* **v0.8:** secret resolver plugin system + load_session fallback ([#54](https://github.com/patrick204nqh/browserctl/issues/54)) ([69737bf](https://github.com/patrick204nqh/browserctl/commit/69737bf10528ad691a31abf916953325637af597))
+
 ## [0.7.0](https://github.com/patrick204nqh/browserctl/compare/v0.6.0...v0.7.0) (2026-04-28)
 
 

data/lib/browserctl/commands/session.rb

@@ -1,5 +1,12 @@
 # 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
@@ -9,6 +16,13 @@ module Browserctl
 
       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
@@ -23,8 +37,9 @@ module Browserctl
       end
 
       def self.run_save(client, args)
-        name = args.shift or abort "usage: browserctl session save <name>"
-        print_result(client.session_save(name))
+        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)
@@ -42,14 +57,23 @@ module Browserctl
       end
 
       def self.run_export(args)
-        name = args.shift or abort "usage: browserctl session export <name> <path>"
-        dest = args.shift or abort "usage: browserctl session export <name> <path>"
+        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]"
+
         session_dir = File.join(Browserctl::BROWSERCTL_DIR, "sessions", name)
         abort "session '#{name}' not found" unless Dir.exist?(session_dir)
 
         dest = File.expand_path(dest)
-        pid = Process.spawn("zip", "-r", dest, name, chdir: File.join(Browserctl::BROWSERCTL_DIR, "sessions"))
-        Process.wait(pid)
+
+        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
 
@@ -60,10 +84,154 @@ module Browserctl
 
         sessions_dir = File.join(Browserctl::BROWSERCTL_DIR, "sessions")
         FileUtils.mkdir_p(sessions_dir)
-        pid = Process.spawn("unzip", "-o", zip_path, "-d", sessions_dir)
-        Process.wait(pid)
+
+        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
+
         puts({ ok: true }.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/errors.rb

@@ -22,4 +22,7 @@ module Browserctl
   class DomainNotAllowed < Error; def self.default_code = "domain_not_allowed" end
   class TimeoutError     < Error; def self.default_code = "timeout"            end
   class KeyNotFound      < Error; def self.default_code = "key_not_found"      end
+
+  class WorkflowError < StandardError; end
+  class SecretResolverError < WorkflowError; end
 end

data/lib/browserctl/secret_resolver_registry.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Browserctl
+  class SecretResolverRegistry
+    @mutex    = Mutex.new
+    @registry = {}
+
+    def self.register(resolver_class)
+      instance = resolver_class.new
+      @mutex.synchronize { @registry[resolver_class.scheme] = instance }
+    end
+
+    def self.resolve(secret_ref)
+      scheme, reference = secret_ref.split("://", 2)
+      resolver = @mutex.synchronize { @registry[scheme] }
+      raise SecretResolverError, "unknown secret resolver scheme '#{scheme}'" unless resolver
+      unless resolver.available?
+        raise SecretResolverError,
+              "'#{scheme}://' resolver is not available in this environment"
+      end
+
+      resolver.resolve(reference)
+    rescue SecretResolverError
+      raise
+    rescue StandardError => e
+      raise SecretResolverError, "secret resolution failed for #{secret_ref.inspect}: #{e.message}"
+    end
+
+    def self.registered?(scheme)
+      @mutex.synchronize { @registry.key?(scheme) }
+    end
+
+    def self.reset!
+      @mutex.synchronize { @registry.clear }
+    end
+  end
+end

data/lib/browserctl/secret_resolvers/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module SecretResolvers
+    class Base
+      def self.scheme
+        raise NotImplementedError, "#{name}.scheme not implemented"
+      end
+
+      def available? = true
+
+      def resolve(_reference)
+        raise NotImplementedError, "#{self.class.name}#resolve not implemented"
+      end
+    end
+  end
+end

data/lib/browserctl/secret_resolvers/env.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module SecretResolvers
+    class Env < Base
+      def self.scheme = "env"
+
+      def resolve(reference)
+        ENV.fetch(reference) { raise SecretResolverError, "env var '#{reference}' is not set" }
+      end
+    end
+  end
+end

data/lib/browserctl/secret_resolvers/macos_keychain.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Browserctl
+  module SecretResolvers
+    class MacOSKeychain < Base
+      def self.scheme = "keychain"
+
+      def available?
+        RUBY_PLATFORM.include?("darwin") && system("which security > /dev/null 2>&1")
+      end
+
+      def resolve(reference)
+        service, account = reference.split("/", 2)
+        if account.nil?
+          raise SecretResolverError,
+                "keychain reference must be 'service/account', got: #{reference.inspect}"
+        end
+
+        result, status = Open3.capture2("security", "find-generic-password",
+                                        "-a", account, "-s", service, "-w")
+        raise SecretResolverError, "keychain item not found: #{reference}" unless status.success?
+
+        result.chomp
+      end
+    end
+  end
+end

data/lib/browserctl/secret_resolvers/one_password.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Browserctl
+  module SecretResolvers
+    class OnePassword < Base
+      def self.scheme = "op"
+
+      def available?
+        system("which op > /dev/null 2>&1")
+      end
+
+      def resolve(reference)
+        result, status = Open3.capture2("op", "read", "op://#{reference}")
+        raise SecretResolverError, "1Password item not found: op://#{reference}" unless status.success?
+
+        result.chomp
+      end
+    end
+  end
+end

data/lib/browserctl/secret_resolvers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "secret_resolver_registry"
+require_relative "secret_resolvers/base"
+require_relative "secret_resolvers/env"
+require_relative "secret_resolvers/macos_keychain"
+require_relative "secret_resolvers/one_password"
+
+Browserctl::SecretResolverRegistry.register(Browserctl::SecretResolvers::Env)
+Browserctl::SecretResolverRegistry.register(Browserctl::SecretResolvers::MacOSKeychain)
+Browserctl::SecretResolverRegistry.register(Browserctl::SecretResolvers::OnePassword)
+
+user_resolvers = File.expand_path("~/.browserctl/resolvers.rb")
+load user_resolvers if File.exist?(user_resolvers)

data/lib/browserctl/session.rb

@@ -2,6 +2,9 @@
 
 require "fileutils"
 require "json"
+require "openssl"
+require "securerandom"
+require "open3"
 require_relative "constants"
 
 module Browserctl
@@ -10,6 +13,8 @@ module Browserctl
 
     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))
 
@@ -22,29 +27,65 @@ module Browserctl
       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:)
+    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_secret(File.join(dir, "cookies.json"),    cookies)
-      write_secret(File.join(dir, "local_storage.json"), local_storage)
-      return if session_storage.empty?
+      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
 
-      write_secret(File.join(dir, "session_storage.json"), session_storage)
+      raise Browserctl::Error, "session encryption requires macOS Keychain (darwin only)" unless keychain_available?
+
+      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 "session '#{session_name}' not found" unless Dir.exist?(dir)
 
-      {
-        metadata: JSON.parse(File.read(File.join(dir, "metadata.json")), symbolize_names: true),
-        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)
-      }
+      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)
@@ -59,12 +100,87 @@ module Browserctl
       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 > /dev/null 2>&1")
+    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.write(path, JSON.generate(data))
     end
@@ -75,5 +191,11 @@ module Browserctl
       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

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -2,11 +2,11 @@
 
 require "timeout"
 require_relative "client"
+require_relative "errors"
+require_relative "secret_resolvers"
 
 module Browserctl
-  class WorkflowError < StandardError; end
-
-  ParamDef = Struct.new(:name, :required, :secret, :default, keyword_init: true)
+  ParamDef = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
   StepResult = Struct.new(:name, :ok, :error, keyword_init: true)
   StepDef = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
 
@@ -60,18 +60,27 @@ module Browserctl
       res
     end
 
-    def save_session(session_name)
-      res = @client.session_save(session_name)
+    def save_session(session_name, encrypt: false)
+      res = @client.session_save(session_name, encrypt: encrypt)
       raise WorkflowError, res[:error] if res[:error]
 
       res
     end
 
-    def load_session(session_name)
+    def load_session(session_name, fallback: nil)
       res = @client.session_load(session_name)
-      raise WorkflowError, res[:error] if res[:error]
+      return res unless res[:error]
 
-      res
+      raise WorkflowError, res[:error] unless fallback
+
+      invoke(fallback.to_s)
+      res2 = @client.session_load(session_name)
+      if res2[:error]
+        raise WorkflowError,
+              "session '#{session_name}' still unavailable after running fallback '#{fallback}'"
+      end
+
+      res2
     end
 
     def list_sessions
@@ -172,8 +181,10 @@ module Browserctl
       @description = text
     end
 
-    def param(name, required: false, secret: false, default: nil)
-      @param_defs[name] = ParamDef.new(name: name, required: required, secret: secret, default: default)
+    def param(name, required: false, secret: false, default: nil, secret_ref: nil)
+      secret = true if secret_ref
+      @param_defs[name] =
+        ParamDef.new(name: name, required: required, secret: secret, default: default, secret_ref: secret_ref)
     end
 
     def step(label, retry_count: 0, timeout: nil, &block)
@@ -223,7 +234,11 @@ module Browserctl
 
     def resolve_params(provided)
       @param_defs.each_with_object({}) do |(name, defn), out|
-        val = provided[name] || defn.default
+        val = if defn.secret_ref
+                SecretResolverRegistry.resolve(defn.secret_ref)
+              else
+                provided[name] || defn.default
+              end
         raise WorkflowError, "required param '#{name}' missing" if defn.required && val.nil?
 
         out[name] = val

data/lib/browserctl.rb

@@ -3,6 +3,7 @@
 require_relative "browserctl/version"
 require_relative "browserctl/constants"
 require_relative "browserctl/errors"
+require_relative "browserctl/secret_resolvers"
 require_relative "browserctl/workflow"
 require_relative "browserctl/runner"
 require_relative "browserctl/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-28 00:00:00.000000000 Z
+date: 2026-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -139,8 +139,6 @@ files:
 - bin/browserd
 - bin/setup
 - examples/cloudflare_hitl.rb
-- examples/smoke/params_file.rb
-- examples/smoke/store_fetch.rb
 - examples/test_automation_practices/advanced/ab_testing.rb
 - examples/test_automation_practices/advanced/broken_images.rb
 - examples/test_automation_practices/advanced/file_download.rb
@@ -191,6 +189,12 @@ files:
 - lib/browserctl/policy.rb
 - lib/browserctl/recording.rb
 - lib/browserctl/runner.rb
+- lib/browserctl/secret_resolver_registry.rb
+- lib/browserctl/secret_resolvers.rb
+- lib/browserctl/secret_resolvers/base.rb
+- lib/browserctl/secret_resolvers/env.rb
+- lib/browserctl/secret_resolvers/macos_keychain.rb
+- lib/browserctl/secret_resolvers/one_password.rb
 - lib/browserctl/server.rb
 - lib/browserctl/server/command_dispatcher.rb
 - lib/browserctl/server/handlers/cookies.rb

data/examples/smoke/params_file.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-#
-# Smoke test for --params file loading (Task 7.5).
-#
-# Run with:
-#   browserctl workflow run examples/smoke/params_file.rb --params examples/smoke/params_file.yml
-#
-# The workflow logs in using credentials from the params file and asserts
-# the secure area is reached — proving the params were loaded and available.
-
-Browserctl.workflow "smoke/params_file" do
-  desc "Smoke: load credentials from a --params file and use them in a workflow"
-
-  param :username, required: true
-  param :password, required: true, secret: true
-  param :base_url, default: "https://the-internet.herokuapp.com"
-
-  step "open login page" do
-    open_page(:main, url: "#{base_url}/login")
-  end
-
-  step "fill credentials from params file" do
-    puts "  [params] username = #{username.inspect}"
-    puts "  [params] password = (#{password.length} chars, secret)"
-    page(:main).fill("input#username", username)
-    page(:main).fill("input#password", password)
-    page(:main).click("button[type=submit]")
-  end
-
-  step "assert login succeeded" do
-    page(:main).wait(".flash.success", timeout: 10)
-    assert page(:main).url.include?("/secure"), "expected redirect to /secure — params may not have loaded"
-    puts "  [ok] reached secure area — params file loaded correctly"
-  end
-end

data/examples/smoke/store_fetch.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-#
-# Smoke test for WorkflowContext#store / #fetch (Task 7.3).
-#
-# Uses the-internet's dynamic loading example: click Start, wait for "Hello World!",
-# capture the text in step 1, assert it is still accessible in step 2 via fetch.
-
-Browserctl.workflow "smoke/store_fetch" do
-  desc "Smoke: store a value in one step and retrieve it in a later step"
-
-  param :base_url, default: "https://the-internet.herokuapp.com"
-
-  step "open dynamic loading page" do
-    open_page(:main, url: "#{base_url}/dynamic_loading/1")
-  end
-
-  step "click start and capture loaded text" do
-    page(:main).click("div#start button")
-    page(:main).wait("div#finish", timeout: 10)
-    text = client.evaluate("main", "document.querySelector('div#finish h4')?.innerText?.trim()")[:result]
-    assert text && !text.empty?, "expected loaded text, got: #{text.inspect}"
-    store(:loaded_text, text)
-    puts "  [store] loaded_text = #{text.inspect}"
-  end
-
-  step "fetch value from previous step and assert" do
-    text = fetch(:loaded_text)
-    puts "  [fetch] loaded_text = #{text.inspect}"
-    assert text == "Hello World!", "expected 'Hello World!', got: #{text.inspect}"
-  end
-
-  step "confirm fetch raises for unknown key" do
-    fetch(:nonexistent_key)
-    assert false, "expected WorkflowError was not raised"
-  rescue Browserctl::WorkflowError => e
-    puts "  [ok] WorkflowError raised as expected: #{e.message}"
-  end
-end