browserctl 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e63d2425e4bbd57beefebf31e3f616a3183823f467b08c89ba6a1e2bb32cca0b
-  data.tar.gz: 8f12b646d805237a46b2bba2c194fb91c21834dc78648db97a4f74b0cc672de6
+  metadata.gz: e85e284d37a585d84857db9f02a93bc7d9aacbf5c026da8ab06559fdff121f16
+  data.tar.gz: 76dbe3a44dee51d1c520dc0bd4d282790309efab1ecc5567fcee585b064660f1
 SHA512:
-  metadata.gz: 50521d3c938c009818d85c93b793c55f5ec2b6d7ae64ec0daae5bf337d793f795189f870d1451d5dca18b285c428a2dd48ec1c0b6af210e6e7c3b41a49c14989
-  data.tar.gz: fe973906dbfe35134aaa32c2e3080196febaa99dc4c8858683ceb9a9e41579f9a40b7ca7865af67ba946a6b2acc68dd7bafa31036daafeebe96e23edbd3f53c6
+  metadata.gz: e66d36468423be0212176d8d40df94c5e10ba3d5f23663041b502c0d481580f94f12f308deaffac18b25fef1cc0bd644dac110e4d98ce365574ef6aa53dc4784
+  data.tar.gz: b147ca301c15e728b9bf6e3682bcf975f7f105adadd77d62db9a6a68fa8a05cd73533562f198b0825abc99f45ee73c04cf50aa2205d840d0181f3b599e9f7093

data/CHANGELOG.md

@@ -10,6 +10,14 @@ 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)
 
 

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/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.8.0"
+  VERSION = "0.8.1"
 end

data/lib/browserctl/workflow.rb

@@ -60,8 +60,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

metadata

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