browserctl 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e63d2425e4bbd57beefebf31e3f616a3183823f467b08c89ba6a1e2bb32cca0b
-  data.tar.gz: 8f12b646d805237a46b2bba2c194fb91c21834dc78648db97a4f74b0cc672de6
+  metadata.gz: c5145a9c65fc1dc92bd238aecd15c672286dfa41005333dbaa1e6a613834c9fc
+  data.tar.gz: 0f1c56d87a58b41fbdea2e3ec1abf211bcf08a3677348d34565301f15bb76e96
 SHA512:
-  metadata.gz: 50521d3c938c009818d85c93b793c55f5ec2b6d7ae64ec0daae5bf337d793f795189f870d1451d5dca18b285c428a2dd48ec1c0b6af210e6e7c3b41a49c14989
-  data.tar.gz: fe973906dbfe35134aaa32c2e3080196febaa99dc4c8858683ceb9a9e41579f9a40b7ca7865af67ba946a6b2acc68dd7bafa31036daafeebe96e23edbd3f53c6
+  metadata.gz: 162679d64a18bfb241ef1312a7ecfac12cc312407ccd598bc0741c2f985d1754dbdcbe00112ee2cc522a3987b88d8cd34dd4799b48651238efb548348123d58f
+  data.tar.gz: 710809a3eb707ad0f1f7300c77cb4b6cfdc4f631dc7f1e02b4b426262164b061d7008ba1901e501483e85a09ecb7be63fd60afa08dba9039b79670e711532fa4

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.2](https://github.com/patrick204nqh/browserctl/compare/v0.8.1...v0.8.2) (2026-04-29)
+
+
+### Bug Fixes
+
+* v0.8.2 UX polish — describe secret_ref, fallback hint, cross-platform encrypt guidance ([#65](https://github.com/patrick204nqh/browserctl/issues/65)) ([2fe5ea4](https://github.com/patrick204nqh/browserctl/commit/2fe5ea4da0997dc2ab2c3a0696fc819e3fffca40))
+
+## [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)
 
 

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/runner.rb

@@ -109,7 +109,11 @@ module Browserctl
     end
 
     def format_params(defn)
-      defn.param_defs.transform_values { |p| { required: p.required, secret: p.secret, default: p.default } }
+      defn.param_defs.transform_values do |p|
+        entry = { required: p.required, secret: p.secret, default: p.default }
+        entry[:secret_ref] = p.secret_ref if p.secret_ref
+        entry
+      end
     end
   end
 end

data/lib/browserctl/secret_resolver_registry.rb

@@ -16,9 +16,13 @@ module Browserctl
       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"
+        msg = "'#{scheme}://' resolver is not available in this environment"
+        if scheme == "keychain"
+          msg += "\n  Use env://YOUR_VAR_NAME to source secrets from environment variables instead."
+        end
+        raise SecretResolverError, msg
       end
 
       resolver.resolve(reference)

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,70 @@ 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)
+      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 "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 +105,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 +196,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.8.0"
+  VERSION = "0.8.2"
 end

data/lib/browserctl/workflow.rb

@@ -4,6 +4,7 @@ require "timeout"
 require_relative "client"
 require_relative "errors"
 require_relative "secret_resolvers"
+require_relative "session"
 
 module Browserctl
   ParamDef = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
@@ -60,8 +61,8 @@ 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
@@ -76,8 +77,11 @@ module Browserctl
       invoke(fallback.to_s)
       res2 = @client.session_load(session_name)
       if res2[:error]
-        raise WorkflowError,
-              "session '#{session_name}' still unavailable after running fallback '#{fallback}'"
+        msg = "session '#{session_name}' still unavailable after running fallback '#{fallback}'"
+        unless Session.exist?(session_name)
+          msg += "\n  Hint: '#{fallback}' did not call save_session(\"#{session_name}\") — add it as the last step."
+        end
+        raise WorkflowError, msg
       end
 
       res2

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Patrick