browserctl 0.10.0 → 0.11.0

data/lib/browserctl/state/bundle.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "securerandom"
+require_relative "../errors"
+
+module Browserctl
+  module State
+    # Single-file portable codec for browserctl session state — the .bctl
+    # bundle. Wraps a plaintext manifest (origins, flow binding, timestamps)
+    # alongside a payload of cookies + storage. The manifest is always
+    # readable without a passphrase (so `state info` can show origins and
+    # expiry); the payload is optionally encrypted.
+    #
+    # Wire format (big-endian):
+    #
+    #   magic:        "BCTL\x00"           5 bytes
+    #   version:      0x01                 1 byte
+    #   flags:        bit 0 = encrypted    1 byte
+    #   reserved:     0x00                 1 byte
+    #   manifest_len:                      4 bytes
+    #   manifest:     JSON                 manifest_len bytes (always plaintext)
+    #   payload_len:                       4 bytes
+    #   payload:      see below            payload_len bytes
+    #   footer:       32 bytes
+    #
+    # When flags & 0x01 is unset:
+    #   payload  = JSON bytes (plaintext)
+    #   footer   = SHA-256 over magic..payload (corruption detection)
+    #
+    # When flags & 0x01 is set:
+    #   payload  = salt(16) || nonce(12) || ciphertext || tag(16)
+    #   footer   = HMAC-SHA-256(hmac_key, magic..payload)
+    #   salt drives PBKDF2(passphrase, salt, 200_000, SHA-256, 64-byte output);
+    #   first 32 bytes are the AES-256-GCM encryption key, last 32 bytes are
+    #   the HMAC-SHA-256 key.
+    #
+    # Reuses the same AES-256-GCM primitive as v0.8 session encryption
+    # (lib/browserctl/session.rb). The two will share a Crypto module in a
+    # follow-up; duplicated here to keep this PR focused.
+    class Bundle
+      MAGIC          = "BCTL\x00".b.freeze
+      VERSION        = 1
+      FLAG_ENCRYPTED = 0x01
+      HEADER_SIZE    = MAGIC.bytesize + 3 # version + flags + reserved
+      LEN_SIZE       = 4
+      FOOTER_SIZE    = 32
+      SALT_SIZE      = 16
+      NONCE_SIZE     = 12
+      TAG_SIZE       = 16
+      PBKDF2_ITERS   = 200_000
+
+      class BundleError      < Browserctl::Error; def self.default_code = "bundle_error"      end
+      class TamperError      < BundleError;       def self.default_code = "bundle_tampered"   end
+      class PassphraseError  < BundleError;       def self.default_code = "bundle_passphrase" end
+
+      # Encodes manifest + payload into a single binary blob.
+      #
+      # @param manifest [Hash] plaintext manifest (always readable)
+      # @param payload  [Hash] cookies/storage; encrypted when passphrase given
+      # @param passphrase [String, nil] when given, payload is encrypted and
+      #   the footer is an HMAC. When nil, payload is plaintext and the
+      #   footer is a SHA-256 digest.
+      def self.encode(manifest:, payload:, passphrase: nil)
+        manifest_bytes = JSON.generate(manifest).b
+        payload_json   = JSON.generate(payload).b
+        flags          = 0
+        hmac_key       = nil
+
+        if passphrase
+          salt = SecureRandom.bytes(SALT_SIZE)
+          enc_key, hmac_key = derive_keys(passphrase, salt)
+          payload_bytes = salt + aes_gcm_encrypt(payload_json, enc_key)
+          flags |= FLAG_ENCRYPTED
+        else
+          payload_bytes = payload_json
+        end
+
+        body = build_body(flags, manifest_bytes, payload_bytes)
+        body + footer_for(body, hmac_key)
+      end
+
+      # Decodes a blob, verifying the footer and decrypting payload when
+      # encrypted. Raises TamperError on digest/HMAC mismatch and
+      # PassphraseError when an encrypted bundle is decoded without a
+      # passphrase or with the wrong one.
+      def self.decode(blob, passphrase: nil)
+        magic, version, flags = read_header!(blob)
+        raise BundleError, "unsupported bundle version #{version}" unless version == VERSION
+
+        manifest_bytes, payload_bytes, footer = read_sections!(blob)
+        body = blob.byteslice(0, blob.bytesize - FOOTER_SIZE)
+
+        encrypted = flags.anybits?(FLAG_ENCRYPTED)
+        verify_footer!(body, footer, encrypted: encrypted, passphrase: passphrase)
+
+        manifest = JSON.parse(manifest_bytes, symbolize_names: true)
+        payload  = decode_payload(payload_bytes, encrypted: encrypted, passphrase: passphrase)
+
+        { manifest: manifest, payload: payload, magic: magic, version: version, encrypted: encrypted }
+      end
+
+      # Reads the manifest without verifying the footer or decrypting the
+      # payload. Use for `state info` and similar read-only queries.
+      def self.peek_manifest(blob)
+        _, version, = read_header!(blob)
+        raise BundleError, "unsupported bundle version #{version}" unless version == VERSION
+
+        manifest_bytes, = read_sections!(blob)
+        JSON.parse(manifest_bytes, symbolize_names: true)
+      end
+
+      def self.build_body(flags, manifest_bytes, payload_bytes)
+        header = MAGIC + [VERSION, flags, 0].pack("CCC")
+        header +
+          [manifest_bytes.bytesize].pack("N") + manifest_bytes +
+          [payload_bytes.bytesize].pack("N") + payload_bytes
+      end
+      private_class_method :build_body
+
+      def self.footer_for(body, hmac_key)
+        if hmac_key
+          OpenSSL::HMAC.digest("SHA256", hmac_key, body)
+        else
+          OpenSSL::Digest.digest("SHA256", body)
+        end
+      end
+      private_class_method :footer_for
+
+      def self.read_header!(blob)
+        raise BundleError, "blob too small for header" if blob.bytesize < HEADER_SIZE + (2 * LEN_SIZE) + FOOTER_SIZE
+
+        magic = blob.byteslice(0, MAGIC.bytesize)
+        raise BundleError, "bad magic — not a .bctl bundle" unless magic == MAGIC
+
+        version, flags, _reserved = blob.byteslice(MAGIC.bytesize, 3).unpack("CCC")
+        [magic, version, flags]
+      end
+      private_class_method :read_header!
+
+      def self.read_sections!(blob)
+        cursor          = HEADER_SIZE
+        manifest_len    = blob.byteslice(cursor, LEN_SIZE).unpack1("N")
+        cursor         += LEN_SIZE
+        manifest_bytes  = blob.byteslice(cursor, manifest_len)
+        cursor         += manifest_len
+        payload_len     = blob.byteslice(cursor, LEN_SIZE).unpack1("N")
+        cursor         += LEN_SIZE
+        payload_bytes   = blob.byteslice(cursor, payload_len)
+        cursor         += payload_len
+        footer          = blob.byteslice(cursor, FOOTER_SIZE)
+
+        unless manifest_bytes && payload_bytes && footer && footer.bytesize == FOOTER_SIZE
+          raise BundleError, "truncated bundle"
+        end
+
+        [manifest_bytes, payload_bytes, footer]
+      end
+      private_class_method :read_sections!
+
+      def self.verify_footer!(body, footer, encrypted:, passphrase:)
+        if encrypted
+          raise PassphraseError, "encrypted bundle requires a passphrase" unless passphrase
+
+          # We need the HMAC key, which depends on the salt embedded in the
+          # payload. Pull the salt from the payload bytes inside `body`.
+          salt = extract_salt!(body)
+          _, hmac_key = derive_keys(passphrase, salt)
+          expected = OpenSSL::HMAC.digest("SHA256", hmac_key, body)
+          raise PassphraseError, "wrong passphrase or tampered bundle" unless secure_eq?(footer, expected)
+        else
+          expected = OpenSSL::Digest.digest("SHA256", body)
+          raise TamperError, "bundle digest mismatch — file is corrupted or modified" unless secure_eq?(footer,
+                                                                                                        expected)
+        end
+      end
+      private_class_method :verify_footer!
+
+      def self.extract_salt!(body)
+        cursor          = HEADER_SIZE
+        manifest_len    = body.byteslice(cursor, LEN_SIZE).unpack1("N")
+        cursor         += LEN_SIZE + manifest_len + LEN_SIZE
+        body.byteslice(cursor, SALT_SIZE) or raise BundleError, "encrypted payload missing salt"
+      end
+      private_class_method :extract_salt!
+
+      def self.decode_payload(bytes, encrypted:, passphrase:)
+        if encrypted
+          salt       = bytes.byteslice(0, SALT_SIZE)
+          ciphertext = bytes.byteslice(SALT_SIZE, bytes.bytesize - SALT_SIZE)
+          enc_key, = derive_keys(passphrase, salt)
+          plaintext  = aes_gcm_decrypt(ciphertext, enc_key)
+          JSON.parse(plaintext)
+        else
+          JSON.parse(bytes)
+        end
+      rescue OpenSSL::Cipher::CipherError
+        raise PassphraseError, "wrong passphrase — payload could not be decrypted"
+      end
+      private_class_method :decode_payload
+
+      def self.derive_keys(passphrase, salt)
+        material = OpenSSL::PKCS5.pbkdf2_hmac(passphrase.to_s, salt, PBKDF2_ITERS, 64, "SHA256")
+        [material.byteslice(0, 32), material.byteslice(32, 32)]
+      end
+      private_class_method :derive_keys
+
+      def self.aes_gcm_encrypt(plaintext, key)
+        cipher = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.encrypt
+        cipher.key = key
+        nonce = SecureRandom.bytes(NONCE_SIZE)
+        cipher.iv = nonce
+        ct = cipher.update(plaintext) + cipher.final
+        nonce + ct + cipher.auth_tag
+      end
+      private_class_method :aes_gcm_encrypt
+
+      def self.aes_gcm_decrypt(blob, key)
+        nonce      = blob.byteslice(0, NONCE_SIZE)
+        tag        = blob.byteslice(-TAG_SIZE, TAG_SIZE)
+        ciphertext = blob.byteslice(NONCE_SIZE, blob.bytesize - NONCE_SIZE - TAG_SIZE)
+
+        cipher = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.decrypt
+        cipher.key      = key
+        cipher.iv       = nonce
+        cipher.auth_tag = tag
+        cipher.update(ciphertext) + cipher.final
+      end
+      private_class_method :aes_gcm_decrypt
+
+      def self.secure_eq?(actual, expected)
+        return false if actual.bytesize != expected.bytesize
+
+        OpenSSL.fixed_length_secure_compare(actual, expected)
+      end
+      private_class_method :secure_eq?
+    end
+  end
+end

data/lib/browserctl/state/transport.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "../errors"
+
+module Browserctl
+  module State
+    # Pluggable transport for moving .bctl bundles in and out of remote
+    # systems. Each transport responds to:
+    #
+    #   .scheme   String — URI scheme it handles ("file", "s3", "op", ...)
+    #   #handles?(uri)  -> Boolean
+    #   #available?     -> Boolean (e.g. CLI tool present, network reachable)
+    #   #read(uri)      -> binary String (the bundle bytes)
+    #   #write(uri, blob) -> nil; raises on failure
+    #
+    # Transports are matched by URI scheme. A bare path with no scheme falls
+    # through to the FileTransport.
+    module Transport
+      class TransportError < Browserctl::Error; def self.default_code = "transport_error" end
+
+      class << self
+        def registry
+          @registry ||= []
+        end
+
+        def register(transport)
+          registry << transport
+          transport
+        end
+
+        def for(uri)
+          parsed = parse(uri)
+          match  = registry.find { |t| t.handles?(parsed) }
+          raise TransportError, "no transport for #{uri.inspect}" unless match
+
+          unless match.available?
+            scheme = parsed.scheme || "file"
+            raise TransportError, "transport for '#{scheme}://' is not available — install the underlying CLI"
+          end
+
+          [match, parsed]
+        end
+
+        def parse(uri)
+          uri.is_a?(URI) ? uri : URI.parse(uri.to_s)
+        rescue URI::InvalidURIError
+          # bare path with characters URI rejects — treat as file
+          URI.parse("file://#{uri}")
+        end
+      end
+
+      class Base
+        def self.scheme = raise NotImplementedError
+
+        def handles?(parsed)
+          parsed.scheme.nil? || parsed.scheme == self.class.scheme
+        end
+
+        def available? = true
+      end
+    end
+  end
+end

data/lib/browserctl/state/transports/file.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../transport"
+
+module Browserctl
+  module State
+    module Transports
+      # Default transport — reads/writes plain files. Handles bare paths and
+      # `file://` URIs. Always available.
+      class File < Transport::Base
+        def self.scheme = "file"
+
+        def read(parsed)
+          path = local_path(parsed)
+          raise Transport::TransportError, "file not found: #{path}" unless ::File.exist?(path)
+
+          ::File.binread(path)
+        end
+
+        def write(parsed, blob)
+          path = local_path(parsed)
+          FileUtils.mkdir_p(::File.dirname(path))
+          ::File.open(path, "wb", 0o600) { |f| f.write(blob) }
+        end
+
+        def local_path(parsed)
+          ::File.expand_path(parsed.path.to_s.empty? ? parsed.opaque.to_s : parsed.path)
+        end
+      end
+    end
+  end
+end
+
+Browserctl::State::Transport.register(Browserctl::State::Transports::File.new)

data/lib/browserctl/state/transports/one_password.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tmpdir"
+require_relative "../transport"
+
+module Browserctl
+  module State
+    module Transports
+      # 1Password transport — stores bundles as Documents.
+      # URIs look like `op://Vault/ItemName`.
+      #
+      # The op CLI has no streaming primitive for documents, so we stage
+      # the blob to a tmpfile (chmod 0600) and use `op document create` /
+      # `op document get`.
+      class OnePassword < Transport::Base
+        SAFE_REF = %r{\Aop://[^/]+/[^/]+\z}
+
+        def self.scheme = "op"
+
+        def available?
+          system("which", "op", out: ::File::NULL, err: ::File::NULL)
+        end
+
+        def read(parsed)
+          uri = parsed.to_s
+          validate!(uri)
+          out, err, status = Open3.capture3("op", "read", uri, binmode: true)
+          return out if status.success?
+
+          raise Transport::TransportError, "op read failed: #{err.strip.empty? ? out : err}"
+        end
+
+        def write(parsed, blob)
+          uri = parsed.to_s
+          validate!(uri)
+          vault, title = parse_ref(uri)
+
+          Dir.mktmpdir do |tmp|
+            path = ::File.join(tmp, "#{title}.bctl")
+            ::File.open(path, "wb", 0o600) { |f| f.write(blob) }
+
+            args = ["op", "document", "create", path, "--title", title, "--vault", vault]
+            out, err, status = Open3.capture3(*args)
+            unless status.success?
+              raise Transport::TransportError, "op document create failed: #{err.strip.empty? ? out : err}"
+            end
+          end
+        end
+
+        def validate!(uri)
+          return if SAFE_REF.match?(uri)
+
+          raise Transport::TransportError, "invalid 1Password reference: #{uri.inspect} (expected op://Vault/Item)"
+        end
+
+        def parse_ref(uri)
+          # op://Vault/Item — exactly two segments after the scheme
+          rest = uri.delete_prefix("op://")
+          rest.split("/", 2)
+        end
+      end
+    end
+  end
+end
+
+Browserctl::State::Transport.register(Browserctl::State::Transports::OnePassword.new)

data/lib/browserctl/state/transports/s3.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../transport"
+
+module Browserctl
+  module State
+    module Transports
+      # S3 transport — shells out to the `aws` CLI so we don't drag the
+      # aws-sdk gem into core. URIs look like `s3://bucket/path/key.bctl`.
+      # Credentials/region come from the user's normal AWS environment
+      # (env vars, `~/.aws/credentials`, IAM, etc.).
+      class S3 < Transport::Base
+        def self.scheme = "s3"
+
+        def available?
+          system("which", "aws", out: ::File::NULL, err: ::File::NULL)
+        end
+
+        def read(parsed)
+          run!("aws", "s3", "cp", parsed.to_s, "-", binmode: true)
+        end
+
+        def write(parsed, blob)
+          out, err, status = Open3.capture3("aws", "s3", "cp", "-", parsed.to_s, stdin_data: blob, binmode: true)
+          return if status.success?
+
+          raise Transport::TransportError, "aws s3 cp failed: #{err.strip.empty? ? out : err}"
+        end
+
+        def run!(*cmd, binmode: false)
+          out, err, status = Open3.capture3(*cmd, binmode: binmode)
+          return out if status.success?
+
+          raise Transport::TransportError, "#{cmd.first} failed: #{err.strip.empty? ? out : err}"
+        end
+      end
+    end
+  end
+end
+
+Browserctl::State::Transport.register(Browserctl::State::Transports::S3.new)

data/lib/browserctl/state.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require_relative "constants"
+require_relative "errors"
+require_relative "version"
+require_relative "state/bundle"
+require_relative "state/transport"
+require_relative "state/transports/file"
+require_relative "state/transports/s3"
+require_relative "state/transports/one_password"
+
+module Browserctl
+  # Top-level state store: a single .bctl bundle per name under
+  # ~/.browserctl/state/<name>.bctl. Wraps the Bundle codec with on-disk
+  # naming, validation, and a small inventory API used by `state list/info`.
+  #
+  # Data shape inside a bundle:
+  #
+  #   manifest = {
+  #     name:        String,
+  #     version:     1,                       # bundle schema version
+  #     producer:    "browserctl/<gem-ver>",
+  #     created_at:  ISO-8601,
+  #     origins:     [String, ...],
+  #     flow:        String | nil,            # bound flow name, for `state rotate`
+  #     flow_version: String | nil,
+  #     expires_at:  ISO-8601 | nil,          # earliest cookie expiry
+  #     encrypted:   Boolean
+  #   }
+  #
+  #   payload = {
+  #     cookies:         [Hash, ...],
+  #     local_storage:   { origin => { key => value } },
+  #     session_storage: { origin => { key => value } }
+  #   }
+  module State
+    BASE_DIR  = File.join(BROWSERCTL_DIR, "state")
+    SAFE_NAME = /\A[a-zA-Z0-9_-]{1,64}\z/
+    EXTENSION = ".bctl"
+    MANIFEST_VERSION = 1
+
+    def self.path(name) = File.join(BASE_DIR, "#{name}#{EXTENSION}")
+    def self.exist?(name) = File.exist?(path(name))
+
+    def self.validate_name!(name)
+      return if SAFE_NAME.match?(name.to_s)
+
+      raise ArgumentError, "invalid state name #{name.inspect} — use letters, digits, _ or - (max 64 chars)"
+    end
+
+    # Persist a bundle. `payload` is { cookies:, local_storage:, session_storage: }.
+    # `manifest_extras` may carry origins (override), flow, flow_version.
+    def self.save(name, payload:, origins: nil, flow: nil, flow_version: nil, passphrase: nil) # rubocop:disable Metrics/ParameterLists
+      validate_name!(name)
+      FileUtils.mkdir_p(BASE_DIR)
+
+      manifest = build_manifest(
+        name: name,
+        origins: origins || derive_origins(payload),
+        flow: flow,
+        flow_version: flow_version,
+        cookies: payload[:cookies] || payload["cookies"] || [],
+        encrypted: !passphrase.nil?
+      )
+
+      blob = Bundle.encode(manifest: manifest, payload: payload, passphrase: passphrase)
+      File.open(path(name), "wb", 0o600) { |f| f.write(blob) }
+      manifest
+    end
+
+    # Load and decode a bundle. Returns { manifest:, payload:, encrypted: }.
+    def self.load(name, passphrase: nil)
+      validate_name!(name)
+      raise Browserctl::Error, "state '#{name}' not found" unless exist?(name)
+
+      Bundle.decode(File.binread(path(name)), passphrase: passphrase)
+    end
+
+    def self.delete(name)
+      validate_name!(name)
+      FileUtils.rm_f(path(name))
+    end
+
+    # Copies the on-disk .bctl bundle to a transport-addressable destination
+    # (file path, s3://bucket/key, op://Vault/Item, or any registered scheme).
+    # Bundle bytes are written verbatim — no re-encoding — so the receiving
+    # side can verify the manifest/payload exactly as produced.
+    def self.export(name, destination)
+      validate_name!(name)
+      raise Browserctl::Error, "state '#{name}' not found" unless exist?(name)
+
+      transport, parsed = Transport.for(destination)
+      blob = ::File.binread(path(name))
+      transport.write(parsed, blob)
+      { name: name, destination: destination, bytes: blob.bytesize }
+    end
+
+    # Pulls a bundle from a transport-addressable source and stores it as a
+    # local state. Validates the magic header before persisting so we never
+    # leave a corrupt bundle in the state directory. `name` defaults to the
+    # source's basename without `.bctl`.
+    def self.import(source, name: nil)
+      transport, parsed = Transport.for(source)
+      blob = transport.read(parsed)
+      raise Bundle::BundleError, "imported blob is not a .bctl bundle" unless blob.start_with?(Bundle::MAGIC)
+
+      manifest = Bundle.peek_manifest(blob)
+      target_name = name || derive_name(source) || manifest[:name]
+      validate_name!(target_name)
+
+      FileUtils.mkdir_p(BASE_DIR)
+      ::File.open(path(target_name), "wb", 0o600) { |f| f.write(blob) }
+      { name: target_name, source: source, bytes: blob.bytesize, encrypted: manifest[:encrypted] }
+    end
+
+    def self.derive_name(uri)
+      base = ::File.basename(uri.to_s.split("?").first.to_s, EXTENSION)
+      return nil if base.empty?
+
+      base
+    end
+    private_class_method :derive_name
+
+    # Read manifests for all stored bundles. Errors on a single file are
+    # surfaced via { error: "...", path: "..." } rather than aborting the list.
+    def self.all
+      return [] unless Dir.exist?(BASE_DIR)
+
+      Dir[File.join(BASE_DIR, "*#{EXTENSION}")].map do |file|
+        info_for(file)
+      end
+    end
+
+    # Inspect a single bundle without decrypting the payload.
+    def self.info(name)
+      validate_name!(name)
+      raise Browserctl::Error, "state '#{name}' not found" unless exist?(name)
+
+      info_for(path(name))
+    end
+
+    def self.info_for(file)
+      blob     = File.binread(file)
+      manifest = Bundle.peek_manifest(blob)
+      manifest.merge(
+        path: file,
+        size: blob.bytesize
+      )
+    rescue Bundle::BundleError => e
+      { name: File.basename(file, EXTENSION), path: file, error: e.message }
+    end
+    private_class_method :info_for
+
+    def self.build_manifest(name:, origins:, flow:, flow_version:, cookies:, encrypted:) # rubocop:disable Metrics/ParameterLists
+      {
+        name: name,
+        version: MANIFEST_VERSION,
+        producer: "browserctl/#{Browserctl::VERSION}",
+        created_at: Time.now.utc.iso8601,
+        origins: Array(origins).compact.uniq,
+        flow: flow,
+        flow_version: flow_version,
+        expires_at: earliest_expiry(cookies),
+        encrypted: encrypted
+      }
+    end
+    private_class_method :build_manifest
+
+    # Origins captured from the payload itself when not overridden. Pulls from
+    # cookie domains and storage keys to cover both navigation-tracked and
+    # cookie-only auth.
+    def self.derive_origins(payload)
+      cookies = fetch_either(payload, :cookies, "cookies", default: [])
+      ls      = fetch_either(payload, :local_storage, "local_storage", default: {})
+      ss      = fetch_either(payload, :session_storage, "session_storage", default: {})
+
+      (origins_from_cookies(cookies) + ls.keys.map(&:to_s) + ss.keys.map(&:to_s)).uniq
+    end
+    private_class_method :derive_origins
+
+    def self.origins_from_cookies(cookies)
+      cookies.filter_map do |c|
+        domain = (c[:domain] || c["domain"]).to_s
+        next if domain.empty?
+
+        domain.start_with?(".") ? "https://#{domain[1..]}" : "https://#{domain}"
+      end
+    end
+    private_class_method :origins_from_cookies
+
+    def self.fetch_either(hash, sym_key, str_key, default:)
+      hash[sym_key] || hash[str_key] || default
+    end
+    private_class_method :fetch_either
+
+    def self.earliest_expiry(cookies)
+      times = cookies.filter_map do |c|
+        v = c[:expires] || c["expires"] || c[:expiresAt] || c["expiresAt"]
+        v&.to_f&.positive? ? Time.at(v.to_f).utc.iso8601 : nil
+      end
+      times.min
+    end
+    private_class_method :earliest_expiry
+  end
+end

data/lib/browserctl/version.rb

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