RubyGems - browserctl - Versions diffs - 0.9.0 → 0.11.0 - Mend

browserctl 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (51) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +45 -0
data/README.md +1 -1
data/bin/browserctl +45 -4
data/lib/browserctl/client.rb +47 -3
data/lib/browserctl/commands/cli_output.rb +16 -3
data/lib/browserctl/commands/flow.rb +123 -0
data/lib/browserctl/commands/state.rb +193 -0
data/lib/browserctl/commands/workflow.rb +62 -4
data/lib/browserctl/constants.rb +1 -1
data/lib/browserctl/detectors/auth_required.rb +128 -0
data/lib/browserctl/detectors.rb +2 -0
data/lib/browserctl/errors.rb +36 -0
data/lib/browserctl/flow.rb +215 -0
data/lib/browserctl/flow_registry.rb +66 -0
data/lib/browserctl/flows/stdlib/basic_auth.rb +30 -0
data/lib/browserctl/flows/stdlib/cloudflare_solve.rb +59 -0
data/lib/browserctl/flows/stdlib/magic_link_email.rb +28 -0
data/lib/browserctl/flows/stdlib/oauth_github.rb +28 -0
data/lib/browserctl/flows/stdlib/oauth_google.rb +30 -0
data/lib/browserctl/flows/stdlib/totp_2fa.rb +61 -0
data/lib/browserctl/recording.rb +212 -26
data/lib/browserctl/replay/context.rb +40 -0
data/lib/browserctl/replay/fingerprint_matcher.rb +86 -0
data/lib/browserctl/replay/snapshot_diff.rb +51 -0
data/lib/browserctl/replay/telemetry.rb +60 -0
data/lib/browserctl/runner.rb +38 -4
data/lib/browserctl/server/command_dispatcher.rb +10 -1
data/lib/browserctl/server/handlers/interaction.rb +3 -3
data/lib/browserctl/server/handlers/navigation.rb +33 -4
data/lib/browserctl/server/handlers/observation.rb +43 -2
data/lib/browserctl/server/handlers/state.rb +149 -0
data/lib/browserctl/server/page_session.rb +9 -7
data/lib/browserctl/server/snapshot_builder.rb +21 -45
data/lib/browserctl/snapshot/annotator.rb +75 -0
data/lib/browserctl/snapshot/extractor.rb +21 -0
data/lib/browserctl/snapshot/fingerprint.rb +88 -0
data/lib/browserctl/snapshot/ref.rb +70 -0
data/lib/browserctl/snapshot/serializer.rb +17 -0
data/lib/browserctl/state/bundle.rb +242 -0
data/lib/browserctl/state/transport.rb +64 -0
data/lib/browserctl/state/transports/file.rb +35 -0
data/lib/browserctl/state/transports/one_password.rb +67 -0
data/lib/browserctl/state/transports/s3.rb +42 -0
data/lib/browserctl/state.rb +208 -0
data/lib/browserctl/version.rb +1 -1
data/lib/browserctl/workflow/flow_wrapper.rb +81 -0
data/lib/browserctl/workflow/promoter.rb +96 -0
data/lib/browserctl/workflow/promotion_ledger.rb +72 -0
data/lib/browserctl/workflow.rb +180 -16
metadata +32 -2

data/lib/browserctl/snapshot/fingerprint.rb ADDED Viewed

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+require "browserctl/snapshot/ref"
+module Browserctl
+  module Snapshot
+    # Builds a per-element fingerprint that survives small DOM changes.
+    #
+    # The fingerprint is later used by the replay layer to rematch an
+    # element when its recorded selector no longer resolves: score the
+    # candidate elements in the new DOM against the recorded fingerprint
+    # and pick the best match above a threshold.
+    #
+    # Shape:
+    #   {
+    #     text:      <accessible name>,
+    #     role:      <ARIA role, explicit or implicit>,
+    #     neighbors: [<short text of nearby siblings>, ...],
+    #     position:  { index: <int>, depth: <int> }
+    #   }
+    class Fingerprint
+      NEIGHBOR_RADIUS = 2 # siblings to capture on each side
+      NEIGHBOR_TEXT_LEN = 40
+      def initialize(ref_deriver: RefDeriver.new)
+        @ref_deriver = ref_deriver
+      end
+      def build(node)
+        {
+          text: accessible_name(node),
+          role: role(node),
+          neighbors: neighbors(node),
+          position: position(node)
+        }
+      end
+      private
+      def role(node)
+        explicit = node["role"]
+        return explicit if explicit && !explicit.empty?
+        RefDeriver::IMPLICIT_ROLE[node.name] || node.name
+      end
+      def accessible_name(node)
+        %w[aria-label placeholder alt title].each do |attr|
+          v = node[attr]
+          return v.strip if v && !v.strip.empty?
+        end
+        node.text.to_s.strip.slice(0, 80)
+      end
+      def neighbors(node)
+        parent = node.parent
+        return [] unless parent.respond_to?(:children)
+        idx = parent.children.to_a.index(node) || 0
+        window = parent.children.to_a[[idx - NEIGHBOR_RADIUS, 0].max...(idx + NEIGHBOR_RADIUS + 1)] || []
+        window
+          .reject { |c| c == node || !c.respond_to?(:name) }
+          .map { |c| neighbor_signal(c) }
+          .reject(&:empty?)
+      end
+      def neighbor_signal(node)
+        text = node.text.to_s.strip.gsub(/\s+/, " ").slice(0, NEIGHBOR_TEXT_LEN)
+        text.empty? ? "" : "#{node.name}:#{text}"
+      end
+      def position(node)
+        idx = node.parent.respond_to?(:children) ? (node.parent.children.to_a.index(node) || 0) : 0
+        { index: idx, depth: depth(node) }
+      end
+      def depth(node)
+        d = 0
+        cur = node.parent
+        while cur.respond_to?(:name) && cur.name != "document"
+          d += 1
+          cur = cur.parent
+        end
+        d
+      end
+    end
+  end
+end

data/lib/browserctl/snapshot/ref.rb ADDED Viewed

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+require "digest"
+module Browserctl
+  module Snapshot
+    # Derives a stable element ref from semantic + structural signals.
+    #
+    # The same DOM element should produce the same ref across two snapshots
+    # of the same page. Inputs to the hash are:
+    #   - role (explicit @role, else implicit ARIA role from tag)
+    #   - accessible name (aria-label || text || placeholder || alt)
+    #   - tag
+    #   - parent path (chain of ancestor tag names up to <html>)
+    #
+    # Collisions within a single snapshot are disambiguated by the caller via
+    # `disambiguate(ref, taken)` — the deriver itself is pure.
+    class RefDeriver
+      IMPLICIT_ROLE = {
+        "a" => "link", "button" => "button", "input" => "textbox",
+        "select" => "combobox", "textarea" => "textbox"
+      }.freeze
+      HASH_LEN = 7
+      def derive(node)
+        signal = [role(node), accessible_name(node), node.name, parent_path(node)].join("|")
+        "e#{Digest::SHA256.hexdigest(signal)[0, HASH_LEN]}"
+      end
+      # Given a candidate ref and a set of already-taken refs in the current
+      # snapshot, return a unique ref. Adds `-2`, `-3`, ... as needed.
+      def disambiguate(ref, taken)
+        return ref unless taken.include?(ref)
+        n = 2
+        n += 1 while taken.include?("#{ref}-#{n}")
+        "#{ref}-#{n}"
+      end
+      private
+      def role(node)
+        explicit = node["role"]
+        return explicit if explicit && !explicit.empty?
+        IMPLICIT_ROLE[node.name] || node.name
+      end
+      def accessible_name(node)
+        %w[aria-label placeholder alt title].each do |attr|
+          v = node[attr]
+          return v.strip if v && !v.strip.empty?
+        end
+        text = node.text.to_s.strip
+        text.empty? ? "" : text.slice(0, 80)
+      end
+      def parent_path(node)
+        parts = []
+        cur = node.parent
+        while cur.respond_to?(:name) && cur.name != "html" && cur.name != "document"
+          parts.unshift(cur.name)
+          cur = cur.parent
+        end
+        parts.join(">")
+      end
+    end
+  end
+end

data/lib/browserctl/snapshot/serializer.rb ADDED Viewed

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+module Browserctl
+  module Snapshot
+    # Stage 3 of the snapshot pipeline.
+    #
+    # Right now this is the identity function — annotated entries are
+    # already in the wire shape clients expect. It exists as a seam so
+    # later milestones can canonicalize, redact, or compress without
+    # touching extraction or annotation.
+    class Serializer
+      def call(entries)
+        entries
+      end
+    end
+  end
+end

data/lib/browserctl/state/bundle.rb ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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)