browserctl 0.12.0 → 0.13.0

data/lib/browserctl/recording.rb

@@ -1,76 +1,46 @@
 # frozen_string_literal: true
 
-require "json"
-require "date"
-require "time"
-require "fileutils"
 require "tmpdir"
-require "uri"
 require_relative "errors"
 require_relative "error/codes"
 
 module Browserctl
-  class Recording # rubocop:disable Metrics/ClassLength
+  # Captures a sequence of daemon commands as a JSONL log and renders it
+  # back out as a Ruby workflow file. This class is the public facade;
+  # the focused responsibilities live under `Browserctl::Recording::*`:
+  #
+  # - `Recording::State`            — singleton over the on-disk marker.
+  # - `Recording::Redactor`         — secret-aware redaction.
+  # - `Recording::LogWriter`        — log file I/O and JSONL formatting.
+  # - `Recording::WorkflowRenderer` — log-to-Ruby workflow translation.
+  class Recording
     RECORDINGS_DIR = File.join(Dir.tmpdir, "browserctl-recordings")
     STATE_FILE     = File.expand_path("~/.browserctl/active_recording")
 
     # Recording-log format version, written into the `_meta` header and
-    # validated when generate_workflow loads a recording. Distinct from
-    # LOG_FORMAT below — that string ("v0.11") tracks the human-readable
-    # log shape; this integer is the machine-readable schema gate per the
-    # WS-1 format-version convention. See docs/reference/format-versions.md.
+    # validated when generate_workflow loads a recording. See
+    # docs/reference/format-versions.md.
     RECORDING_FORMAT_VERSION = 1
     SUPPORTED_FORMAT_VERSIONS = [RECORDING_FORMAT_VERSION].freeze
 
-    RECORDABLE = %w[page_open navigate fill click screenshot evaluate].freeze
-
-    SENSITIVE_PARAM_PATTERN = /\A(token|key|secret|auth|code|access_token|api_key|client_secret|state)\z/ix
-
-    # Selector tokens that signal a fill is targeting a secret-shaped field.
-    # The captured group (or matched substring) is used as the inferred field
-    # name; that name later drives the generated `secret_ref:` placeholder.
-    SECRET_FIELD_PATTERN = /\b(password|passwd|api[_-]?key|token|secret|otp|pin|client[_-]?secret|access[_-]?token)\b/i
-
-    # Conservative thresholds for inferring an explicit wait between recorded
-    # steps. Gaps shorter than the threshold come from natural input cadence;
-    # gaps above it usually mean the page actually had work to do.
-    WAIT_THRESHOLD_SECONDS = 1.5
-    WAIT_PADDING_SECONDS   = 5
-    WAIT_FLOOR_SECONDS     = 5
-
     # Bumped when the recording log shape changes in a way that older
     # tooling (workflow generate, replay) cannot read.
     LOG_FORMAT = "v0.11"
 
+    RECORDABLE = %w[page_open navigate fill click screenshot evaluate].freeze
+
     def self.start(name)
-      FileUtils.mkdir_p(RECORDINGS_DIR, mode: 0o700)
-      FileUtils.mkdir_p(File.dirname(STATE_FILE))
-      File.write(STATE_FILE, name)
-      FileUtils.rm_f(log_path(name))
-      FileUtils.touch(log_path(name))
-      File.chmod(0o600, log_path(name))
-      File.open(log_path(name), "a") do |f|
-        f.puts JSON.generate(
-          cmd: "_meta",
-          format_version: RECORDING_FORMAT_VERSION,
-          log_format: LOG_FORMAT,
-          recording: name,
-          started_at: Time.now.utc.iso8601
-        )
-      end
+      LogWriter.init_log(name)
+      State.write(name)
       name
     end
 
     def self.stop
-      name = active
-      raise Browserctl::Error, "no active recording — run: browserctl record start <name>" unless name
-
-      File.unlink(STATE_FILE)
-      name
+      State.clear!
     end
 
     def self.active
-      File.exist?(STATE_FILE) ? File.read(STATE_FILE).strip : nil
+      State.active
     end
 
     def self.append(cmd, response: nil, **attrs)
@@ -87,24 +57,22 @@ module Browserctl
       entry = { cmd: cmd.to_s, ts: now }.merge(attrs.transform_keys(&:to_s))
       entry.merge!(replay_metadata(response)) if response
 
-      File.open(log_path(name), "a") do |f|
-        f.puts JSON.generate(entry)
-      end
+      LogWriter.append_entry(name, entry)
     end
 
     def self.generate_workflow(name, output_path: nil, keep_log: false)
-      log = log_path(name)
+      log = LogWriter.log_path(name)
       raise Browserctl::Error, "no recording found for '#{name}'" unless File.exist?(log)
 
-      raw   = File.readlines(log).map { |l| JSON.parse(l, symbolize_names: true) }
-      verify_format_version!(raw, path: log)
+      raw   = LogWriter.read_entries(name)
+      LogWriter.verify_format_version!(raw, path: log)
       lines = raw.reject { |l| l[:cmd] == "_meta" }
-      ruby  = build_workflow_ruby(name, lines)
+      ruby  = WorkflowRenderer.render(name, lines)
       File.write(output_path, ruby) if output_path
       warn_about_ref_interactions(lines)
       ruby
     ensure
-      FileUtils.rm_f(log) if log && !keep_log
+      LogWriter.delete_log(name) unless keep_log
     end
 
     def self.warn_about_ref_interactions(lines)
@@ -118,44 +86,19 @@ module Browserctl
     class << self
       private
 
-      # Raises Browserctl::ProtocolMismatch when the recording log's _meta
-      # header is missing or declares a format_version this build does not
-      # support. Mirrors Browserctl::State::Bundle.verify_format_version!.
-      def verify_format_version!(raw_lines, path: nil)
-        meta = raw_lines.first
-        version = meta && meta[:cmd] == "_meta" ? meta[:format_version] : nil
-        return if version && SUPPORTED_FORMAT_VERSIONS.include?(version)
-
-        where = path ? " at #{path}" : ""
-        msg = if version.nil?
-                "recording log#{where} is missing format_version " \
-                  "(supported: #{SUPPORTED_FORMAT_VERSIONS.inspect})"
-              else
-                "recording log#{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
-
-      def log_path(name)
-        File.join(RECORDINGS_DIR, "#{name}.jsonl")
+      def now
+        Time.now.utc.to_f
       end
 
       def record_ref_interaction(recording_name, cmd, attrs, response)
         entry = { cmd: "_ref_interaction", ts: now, action: cmd, ref: attrs[:ref], name: attrs[:name] }
         entry.merge!(replay_metadata(response)) if response
-        File.open(log_path(recording_name), "a") do |f|
-          f.puts JSON.generate(entry)
-        end
+        LogWriter.append_entry(recording_name, entry)
       end
 
       # Pulls the replay-relevant fields out of a daemon response. Each
       # is optional — older daemons or non-resolving commands may omit
       # any of them.
-      def now
-        Time.now.utc.to_f
-      end
-
       def replay_metadata(response)
         meta = {}
         meta[:ref]                  = response[:ref]                  if response[:ref]
@@ -166,228 +109,24 @@ module Browserctl
         meta.transform_keys(&:to_s)
       end
 
-      def build_workflow_ruby(name, commands)
-        steps   = annotated_steps(commands).join("\n\n")
-        secrets = commands.map { |c| c[:secret_field] }.compact.uniq
-        header  = secret_header(secrets)
-        <<~RUBY
-          # frozen_string_literal: true
-          # format_version: #{Browserctl::WORKFLOW_FORMAT_VERSION}
-          #{header}
-          Browserctl.workflow #{name.inspect} do
-            desc "Recorded on #{Date.today}"
-          #{secrets.map { |f| "  param :secret_#{f}, secret: true" }.join("\n")}
-          #{steps.gsub(/^/, '  ')}
-          end
-        RUBY
-      end
-
-      # Walks the recorded events and emits the rendered step strings,
-      # interleaving inferred waits before selector-driven actions whose
-      # preceding gap exceeds WAIT_THRESHOLD_SECONDS, and inferred URL
-      # postconditions after click/fill steps that triggered navigation.
-      def annotated_steps(commands)
-        last_url = {}
-        commands.each_with_index.flat_map do |cmd, i|
-          rendered = []
-          if i.positive? && (wait = inferred_wait_step(commands[i - 1], cmd))
-            rendered << wait
-          end
-          rendered << build_step(cmd)
-          if (post = url_postcondition_step(cmd, last_url))
-            rendered << post
-          end
-          if (snap = snapshot_postcondition_step(cmd))
-            rendered << snap
-          end
-          update_last_url!(cmd, last_url)
-          rendered
-        end
-      end
-
-      # Emits a postcondition assertion when a click/fill resulted in a URL
-      # change. Compares the canonical (scheme+host+path) form so query
-      # strings and fragments don't make every replay flaky.
-      def url_postcondition_step(cmd, last_url)
-        return nil unless %w[click fill].include?(cmd[:cmd])
-        return nil unless cmd[:postcondition_hint] && cmd[:postcondition_hint][:url]
-
-        page = cmd[:name]
-        observed = cmd[:postcondition_hint][:url]
-        prior    = last_url[page]
-        return nil if canonical_url(observed) == canonical_url(prior)
-
-        prefix = canonical_url(observed)
-        return nil unless prefix
-
-        <<~RUBY.chomp
-          step "assert url after #{cmd[:cmd]} on #{page}" do
-            current = page(:#{page}).url
-            assert current.start_with?(#{prefix.inspect}), "expected URL to start with #{prefix}, got \#{current}"
-          end
-        RUBY
-      end
-
-      # Emits an assert_snapshot_stable step when the recording captured a
-      # post-step DOM digest. Under workflow run --check the helper records
-      # drift on mismatch instead of raising, so a wiggly page surfaces in
-      # the report rather than failing the run outright.
-      def snapshot_postcondition_step(cmd)
-        return nil unless %w[click fill].include?(cmd[:cmd])
-        return nil unless cmd[:post_snapshot_digest]
-
-        page = cmd[:name]
-        digest = cmd[:post_snapshot_digest]
-        <<~RUBY.chomp
-          step "assert post-snapshot stable on #{page}" do
-            assert_snapshot_stable(:#{page}, expected_digest: #{digest.inspect})
-          end
-        RUBY
-      end
-
-      def update_last_url!(cmd, last_url)
-        case cmd[:cmd]
-        when "navigate", "page_open"
-          last_url[cmd[:name]] = cmd[:url] if cmd[:url]
-        when "click", "fill"
-          observed = cmd[:postcondition_hint] && cmd[:postcondition_hint][:url]
-          last_url[cmd[:name]] = observed if observed
-        end
-      end
-
-      def canonical_url(url)
-        return nil if url.nil? || url.empty?
-
-        uri = URI.parse(url)
-        path = uri.path.to_s
-        path = "/" if path.empty?
-        "#{uri.scheme}://#{uri.host}#{path}"
-      rescue URI::InvalidURIError
-        nil
-      end
-
-      def inferred_wait_step(prev, current)
-        return nil unless %w[fill click].include?(current[:cmd])
-        return nil unless current[:selector]
-
-        delta = elapsed(prev, current)
-        return nil unless delta && delta >= WAIT_THRESHOLD_SECONDS
-
-        timeout = [WAIT_FLOOR_SECONDS, delta.ceil + WAIT_PADDING_SECONDS].max
-        page = current[:name]
-        sel  = current[:selector]
-        <<~RUBY.chomp
-          # inferred wait: prior step took ~#{format('%.1f', delta)}s
-          step "wait for #{sel} on #{page}" do
-            page(:#{page}).wait(#{sel.inspect}, timeout: #{timeout})
-          end
-        RUBY
-      end
-
-      def elapsed(prev, current)
-        return nil unless prev && current && prev[:ts] && current[:ts]
-
-        current[:ts] - prev[:ts]
-      end
-
-      def secret_header(secrets)
-        return "" if secrets.empty?
-
-        lines = ["# TODO: review the following secret-shaped fields detected during recording.",
-                 "# Configure a secret_ref: source for each before running:"]
-        secrets.each { |f| lines << "#   - secret_#{f}" }
-        "\n#{lines.join("\n")}\n"
-      end
-
-      def build_step(cmd)
-        label, body = step_parts(cmd)
-
-        if body.nil?
-          page_sym = cmd[:name].to_s.gsub(/[^a-zA-Z0-9_]/, "_")
-          action   = cmd[:action].to_s.gsub(/[^a-z_]/, "")
-          return "# TODO: ref-based #{action} on #{cmd[:name].inspect} (ref: #{cmd[:ref].inspect}) — " \
-                 "replace with a stable CSS selector\n" \
-                 "# step #{label.inspect} do\n" \
-                 "#   page(:#{page_sym}).#{action}(\"YOUR_SELECTOR_HERE\")\n" \
-                 "# end"
-        end
-
-        prefix = []
-        prefix << "# NOTE: sensitive query params were redacted during recording" \
-          if cmd[:url].to_s.include?("[REDACTED]")
-        prefix << "# fingerprint fallback: #{cmd[:fingerprint].to_json}" if cmd[:fingerprint]
-
-        head = prefix.empty? ? "" : "#{prefix.join("\n")}\n"
-        "#{head}step #{label.inspect} do\n  #{body}\nend"
-      end
-
-      def step_parts(cmd)
-        return ref_interaction_parts(cmd) if cmd[:cmd] == "_ref_interaction"
-        return selector_parts(cmd) if %w[fill click].include?(cmd[:cmd])
-
-        page = cmd[:name]
-        case cmd[:cmd]
-        when "page_open"  then ["open #{page}", "page(:#{page}).navigate(#{cmd[:url].inspect})"]
-        when "navigate"   then ["navigate #{page}", "page(:#{page}).navigate(#{cmd[:url].inspect})"]
-        when "screenshot" then ["screenshot #{page}", "page(:#{page}).screenshot"]
-        when "evaluate"   then ["eval on #{page}", "page(:#{page}).evaluate(#{cmd[:expression].inspect})"]
-        else ["#{cmd[:cmd]} on #{page}", "# unrecognised command: #{cmd.inspect}"]
-        end
-      end
-
-      def ref_interaction_parts(cmd)
-        ["TODO: ref-based #{cmd[:action]} on #{cmd[:name]} (ref: #{cmd[:ref]})", nil]
-      end
-
-      def selector_parts(cmd)
-        page = cmd[:name]
-        case cmd[:cmd]
-        when "fill"
-          value_arg = cmd[:secret_field] ? "params[:secret_#{cmd[:secret_field]}]" : "params[:fill_value]"
-          ["fill #{cmd[:selector]} on #{page}",
-           "page(:#{page}).fill(#{cmd[:selector].inspect}, #{value_arg})"]
-        when "click"
-          ["click #{cmd[:selector]} on #{page}",
-           "page(:#{page}).click(#{cmd[:selector].inspect})"]
-        end
-      end
-
       def prepare_attrs(cmd, attrs)
         attrs = attrs.except(:capture_post_snapshot)
         if cmd == "fill"
           attrs = attrs.except(:value)
-          field = infer_secret_field(attrs[:selector])
+          field = Redactor.infer_secret_field(attrs[:selector])
           if field
             attrs[:secret_hint]  = true
             attrs[:secret_field] = field
           end
         end
-        attrs[:url] = redact_url(attrs[:url]) if %w[navigate page_open].include?(cmd) && attrs[:url]
+        attrs[:url] = Redactor.redact_url(attrs[:url]) if %w[navigate page_open].include?(cmd) && attrs[:url]
         attrs
       end
-
-      def infer_secret_field(selector)
-        return nil unless selector
-
-        match = selector.match(SECRET_FIELD_PATTERN)
-        return nil unless match
-
-        match[1].downcase.gsub(/[^a-z0-9]/, "_")
-      end
-
-      def redact_url(url)
-        uri = URI.parse(url)
-        return url if uri.query.nil?
-
-        uri.query = uri.query.gsub(/([^&=]+)=([^&]*)/) do |full_match|
-          raw_key = ::Regexp.last_match(1)
-          key = URI.decode_www_form_component(raw_key)
-          key =~ SENSITIVE_PARAM_PATTERN ? "#{raw_key}=[REDACTED]" : full_match
-        end
-        uri.to_s
-      rescue URI::InvalidURIError
-        url
-      end
     end
   end
 end
+
+require_relative "recording/state"
+require_relative "recording/redactor"
+require_relative "recording/log_writer"
+require_relative "recording/workflow_renderer"

data/lib/browserctl/server/command_dispatcher.rb

@@ -11,7 +11,6 @@ require_relative "handlers/hitl"
 require_relative "handlers/devtools"
 require_relative "handlers/daemon_control"
 require_relative "handlers/storage"
-require_relative "handlers/session"
 require_relative "handlers/state"
 require_relative "handlers/interaction"
 require_relative "../detectors"
@@ -30,7 +29,6 @@ module Browserctl
     include Handlers::DevTools
     include Handlers::DaemonControl
     include Handlers::Storage
-    include Handlers::Session
     include Handlers::State
     include Handlers::Interaction
 
@@ -70,10 +68,6 @@ module Browserctl
       "select" => :cmd_select,
       "dialog_accept" => :cmd_dialog_accept,
       "dialog_dismiss" => :cmd_dialog_dismiss,
-      "session_save" => :cmd_session_save,
-      "session_load" => :cmd_session_load,
-      "session_list" => :cmd_session_list,
-      "session_delete" => :cmd_session_delete,
       "state_save" => :cmd_state_save,
       "state_load" => :cmd_state_load,
       "state_list" => :cmd_state_list,
@@ -99,23 +93,38 @@ module Browserctl
     # @param req [Hash{Symbol => Object}] parsed request; must include `:cmd`
     # @return [Hash{Symbol => Object}] response; always includes `:ok` or `:error`
     def dispatch(req)
-      handler = COMMAND_MAP[req[:cmd]]
-      if handler
-        Browserctl.logger.debug("#{req[:cmd]} #{req[:name]}")
-        return send(handler, req)
-      end
+      builtin = dispatch_builtin(req)
+      return builtin if builtin
 
-      if (plugin = Browserctl.lookup_plugin_command(req[:cmd]))
-        Browserctl.logger.debug("plugin:#{req[:cmd]} #{req[:name]}")
-        session = req[:name] ? @global_mutex.synchronize { @pages[req[:name]] } : nil
-        return plugin.call(session, req)
-      end
+      plugin = dispatch_plugin(req)
+      return plugin if plugin
 
       { error: "unknown command: #{req[:cmd]}" }
     end
 
     private
 
+    # Routes the request to a builtin handler if `req[:cmd]` is in COMMAND_MAP.
+    # Returns the handler response, or `nil` if the command isn't a builtin.
+    def dispatch_builtin(req)
+      handler = COMMAND_MAP[req[:cmd]]
+      return nil unless handler
+
+      Browserctl.logger.debug("#{req[:cmd]} #{req[:name]}")
+      send(handler, req)
+    end
+
+    # Routes the request to a registered plugin command if one matches.
+    # Returns the plugin response, or `nil` if no plugin handles `req[:cmd]`.
+    def dispatch_plugin(req)
+      plugin = Browserctl.lookup_plugin_command(req[:cmd])
+      return nil unless plugin
+
+      Browserctl.logger.debug("plugin:#{req[:cmd]} #{req[:name]}")
+      session = req[:name] ? @global_mutex.synchronize { @pages[req[:name]] } : nil
+      plugin.call(session, req)
+    end
+
     def with_page(name)
       session = @global_mutex.synchronize { @pages[name] }
       return { error: "no page named '#{name}'" } unless session

data/lib/browserctl/server/handlers/state.rb

@@ -15,21 +15,23 @@ module Browserctl
           first_session = @global_mutex.synchronize { @pages.values.first }
           return { error: "no open pages — open a page before saving state" } unless first_session
 
-          payload, captured_origins = capture_state_payload
-          manifest = Browserctl::State.save(
-            req[:name],
-            payload: payload,
+          captured, captured_origins = capture_state_payload
+          payload = Browserctl::State::Payload.build(
+            cookies: captured[:cookies],
+            local_storage: captured[:local_storage],
+            session_storage: captured[:session_storage],
             origins: req[:origins] || captured_origins,
             flow: req[:flow],
             flow_version: req[:flow_version],
             passphrase: req[:passphrase]
           )
+          manifest = Browserctl::State.save(req[:name], payload)
 
           {
             ok: true,
             path: Browserctl::State.path(req[:name]),
             origins: manifest[:origins],
-            cookies: payload[:cookies].length,
+            cookies: payload.cookies.length,
             encrypted: manifest[:encrypted]
           }
         rescue Browserctl::Error, ArgumentError => e

data/lib/browserctl/server.rb

@@ -6,7 +6,8 @@ require "fileutils"
 require "timeout"
 require_relative "constants"
 require_relative "logger"
-require_relative "driver"
+require_relative "driver/cdp_page"
+require_relative "driver/cdp"
 require_relative "server/command_dispatcher"
 require_relative "server/idle_watcher"
 require_relative "server/page_session"

data/lib/browserctl/state/bundle.rb

@@ -2,13 +2,13 @@
 
 require "json"
 require "openssl"
-require "securerandom"
 require_relative "../errors"
 require_relative "../error/codes"
+require_relative "../encryption_service"
 
 module Browserctl
   module State
-    # Single-file portable codec for browserctl session state — the .bctl
+    # Single-file portable codec for browserctl persisted 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
@@ -37,9 +37,11 @@ module Browserctl
     #   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.
+    # AES-256-GCM cipher setup and PBKDF2 key derivation are delegated to
+    # `Browserctl::EncryptionService` so this class stays focused on the
+    # bundle wire format. The service translates `OpenSSL::Cipher` errors
+    # into `EncryptionService::DecryptionError`, which we map to
+    # `PassphraseError` for the public API.
     class Bundle
       MAGIC          = "BCTL\x00".b.freeze
       VERSION        = 1
@@ -53,10 +55,12 @@ module Browserctl
       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
+      # Cryptographic primitive sizes are sourced from EncryptionService so
+      # there is exactly one source of truth for cipher parameters.
+      SALT_SIZE      = Browserctl::EncryptionService::SALT_SIZE
+      NONCE_SIZE     = Browserctl::EncryptionService::NONCE_SIZE
+      TAG_SIZE       = Browserctl::EncryptionService::TAG_SIZE
+      PBKDF2_ITERS   = Browserctl::EncryptionService::PBKDF2_ITERS
 
       class BundleError      < Browserctl::Error; def self.default_code = "bundle_error"      end
       class TamperError      < BundleError;       def self.default_code = "bundle_tampered"   end
@@ -77,9 +81,9 @@ module Browserctl
         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)
+          salt = EncryptionService.random_salt
+          enc_key, hmac_key = EncryptionService.derive_keys(passphrase, salt)
+          payload_bytes = salt + EncryptionService.encrypt(payload_json, enc_key)
           flags |= FLAG_ENCRYPTED
         else
           payload_bytes = payload_json
@@ -207,7 +211,7 @@ module Browserctl
           # 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)
+          _, hmac_key = EncryptionService.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
@@ -230,48 +234,17 @@ module Browserctl
         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)
+          enc_key, = EncryptionService.derive_keys(passphrase, salt)
+          plaintext  = EncryptionService.decrypt(ciphertext, enc_key)
           JSON.parse(plaintext)
         else
           JSON.parse(bytes)
         end
-      rescue OpenSSL::Cipher::CipherError
+      rescue EncryptionService::DecryptionError
         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