browserctl 0.10.0 → 0.12.0

data/lib/browserctl/state/bundle.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "securerandom"
+require_relative "../errors"
+require_relative "../error/codes"
+
+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
+      # Manifest-level format version, written as `format_version` and
+      # validated on decode. Distinct from the wire-format byte `VERSION`
+      # above (which gates the binary envelope shape) — this gates the
+      # manifest schema. See docs/reference/format-versions.md.
+      BUNDLE_FORMAT_VERSION = 1
+      SUPPORTED_FORMAT_VERSIONS = [BUNDLE_FORMAT_VERSION].freeze
+      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 = stamp_format_version(manifest)
+        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)
+        verify_format_version!(manifest)
+        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)
+        manifest = JSON.parse(manifest_bytes, symbolize_names: true)
+        verify_format_version!(manifest)
+        manifest
+      end
+
+      # Returns the manifest with `format_version` set as the first key. When
+      # the caller already provided a value we keep it (so encoders can stamp
+      # a future version explicitly); otherwise we stamp the current one.
+      def self.stamp_format_version(manifest)
+        existing = manifest[:format_version] || manifest["format_version"]
+        version = existing || BUNDLE_FORMAT_VERSION
+        rest = manifest.except(:format_version, "format_version")
+        { format_version: version }.merge(rest)
+      end
+      private_class_method :stamp_format_version
+
+      # Raises Browserctl::ProtocolMismatch when the manifest declares no
+      # format_version or one this build does not support. The error carries
+      # the canonical PROTOCOL_MISMATCH code from the v0.12 error taxonomy.
+      def self.verify_format_version!(manifest, path: nil)
+        version = manifest[:format_version] || manifest["format_version"]
+        return if version && SUPPORTED_FORMAT_VERSIONS.include?(version)
+
+        where = path ? " at #{path}" : ""
+        msg = if version.nil?
+                "bundle manifest#{where} is missing format_version " \
+                  "(supported: #{SUPPORTED_FORMAT_VERSIONS.inspect})"
+              else
+                "bundle manifest#{where} declares format_version=#{version.inspect}, " \
+                  "this build supports #{SUPPORTED_FORMAT_VERSIONS.inspect}"
+              end
+        raise Browserctl::ProtocolMismatch.new(msg, code: Browserctl::Error::Codes::PROTOCOL_MISMATCH)
+      end
+      private_class_method :verify_format_version!
+
+      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)