capsium 0.3.0 → 0.6.0

data/lib/capsium/cli/package.rb

@@ -50,9 +50,14 @@ module Capsium
 
       desc "pack PATH_TO_PACKAGE_FOLDER", "Package the files into the package"
       option :force, type: :boolean, default: false, aliases: "-f"
+      option :bundle_deps, type: :boolean, default: false, aliases: "--bundle",
+                           desc: "Embed the resolved dependencies under packages/ " \
+                                 "so the .cap activates with no store or registry"
+      option :store, type: :string, desc: "Package store directory (default: CAPSIUM_STORE)"
+      option :registry, type: :string, desc: "Registry reference (default: CAPSIUM_REGISTRY)"
 
       def pack(path_to_package)
-        package = Capsium::Package.new(path_to_package)
+        package = Capsium::Package.new(path_to_package, store: options[:store])
         packager = Capsium::Packager.new
         packager.pack(package, options)
       end
@@ -66,6 +71,18 @@ module Capsium
         puts "Package unpacked to: #{destination}"
       end
 
+      desc "push PACKAGE_FILE", "Push a .cap into a static registry directory"
+      option :registry, type: :string,
+                        desc: "Registry directory (default: CAPSIUM_REGISTRY)"
+
+      def push(path_to_package)
+        registry = Capsium::Registry.fetch(options[:registry] || ENV.fetch("CAPSIUM_REGISTRY", nil))
+        entry = registry.push(path_to_package)
+        puts "Pushed #{entry.name} #{entry.version} to #{registry.location}"
+      rescue Capsium::Registry::RegistryError => e
+        raise Thor::Error, e.message
+      end
+
       desc "validate PACKAGE_PATH", "Validate a package directory or .cap file"
 
       def validate(path_to_package)
@@ -76,26 +93,34 @@ module Capsium
         raise Thor::Error, "Package validation failed"
       end
 
-      desc "sign PACKAGE_PATH --key KEY.pem [--cert CERT.pem]",
-           "Sign the package (RSA-SHA256) and record the signature in security.json"
+      desc "sign PACKAGE_PATH --key KEY [--cert CERT.pem] [--openpgp]",
+           "Sign the package (RSA-SHA256/X.509, or OpenPGP) into security.json"
       option :key, type: :string, required: true,
-                   desc: "Path to the RSA private key PEM (min 2048 bits)"
-      option :cert, type: :string,
-                    desc: "Path to the X.509 certificate PEM (must match the key)"
+                   desc: "RSA private key PEM (min 2048 bits); OpenPGP secret key with --openpgp"
+      option :cert, type: :string, desc: "X.509 certificate PEM (must match the key)"
+      option :openpgp, type: :boolean, default: false, desc: "OpenPGP detached signature"
 
       def sign(path_to_package)
-        Capsium::Package::Signer.sign_package(path_to_package, options[:key], options[:cert])
+        if options[:openpgp] && options[:cert]
+          raise Thor::Error, "--cert is only used with X.509 signing"
+        end
+
+        if options[:openpgp]
+          Capsium::Package::OpenPgpSigner.sign_package(path_to_package, options[:key])
+        else
+          Capsium::Package::Signer.sign_package(path_to_package, options[:key], options[:cert])
+        end
         puts "Package signed: #{path_to_package}"
       end
 
-      desc "verify-signature PACKAGE_PATH [--cert CERT.pem]",
-           "Verify the package digital signature declared in security.json"
-      option :cert, type: :string,
-                    desc: "Path to the X.509 certificate or public key PEM " \
-                          "(defaults to the key embedded in the package)"
+      desc "verify-signature PACKAGE_PATH [--cert CERT-or-PUB] [--openpgp]",
+           "Verify the declared digital signature (auto-detected from security.json)"
+      option :cert, type: :string, desc: "certificate or public key (default: embedded)"
+      option :openpgp, type: :boolean, default: false, desc: "verify as OpenPGP"
 
       def verify_signature(path_to_package)
-        unless Capsium::Package::Signer.verify_package(path_to_package, options[:cert])
+        verifier = options[:openpgp] ? Capsium::Package::OpenPgpSigner : Capsium::Package::Signer
+        unless verifier.verify_package(path_to_package, options[:cert])
           raise Thor::Error, "Signature verification failed: #{path_to_package}"
         end
 
@@ -104,30 +129,42 @@ module Capsium
         raise Thor::Error, e.message
       end
 
-      desc "encrypt PACKAGE_PATH --public-key PUB.pem -o OUT.cap",
-           "Encrypt a package (AES-256-GCM, RSA-OAEP-SHA256 wrapped DEK)"
-      option :public_key, type: :string, required: true,
-                          desc: "Path to the recipient RSA public key or X.509 certificate PEM"
+      desc "encrypt PACKAGE_PATH -o OUT.cap [--public-key PUB.pem | --openpgp --recipient PUB]",
+           "Encrypt a package (AES-256-GCM; RSA or OpenPGP key management)"
+      option :public_key, type: :string, desc: "recipient RSA public key or X.509 certificate PEM"
+      option :recipient, type: :string, desc: "recipient OpenPGP public key (with --openpgp)"
+      option :openpgp, type: :boolean, default: false, desc: "encrypt for an OpenPGP recipient"
       option :output, type: :string, required: true, aliases: "-o",
                       desc: "Output path for the encrypted .cap"
 
       def encrypt(path_to_package)
-        Capsium::Package::Cipher.new.encrypt(
-          path_to_package, options[:public_key], options[:output]
-        )
+        key = options[:public_key] || options[:recipient]
+        raise Thor::Error, "encrypt requires --public-key or --openpgp --recipient" if key.nil?
+
+        cipher = options[:openpgp] ? Capsium::Package::OpenPgpCipher.new : Capsium::Package::Cipher.new
+        cipher.encrypt(path_to_package, key, options[:output])
         puts "Package encrypted: #{options[:output]}"
       end
 
-      desc "decrypt PACKAGE_PATH --private-key PRIV.pem [-o OUT.cap]",
-           "Decrypt an encrypted package"
-      option :private_key, type: :string, required: true,
-                           desc: "Path to the recipient RSA private key PEM"
+      desc "decrypt PACKAGE_PATH [--private-key PRIV.pem | --openpgp --key SEC.asc] [-o OUT.cap]",
+           "Decrypt an encrypted package (key management auto-detected from the envelope)"
+      option :private_key, type: :string, desc: "recipient RSA private key PEM"
+      option :key, type: :string, desc: "recipient OpenPGP secret key"
+      option :openpgp, type: :boolean, default: false, desc: "decrypt with an OpenPGP key"
       option :output, type: :string, aliases: "-o",
                       desc: "Output path (default: <name>-decrypted.cap)"
 
       def decrypt(path_to_package)
+        key = options[:private_key] || options[:key]
+        raise Thor::Error, "decrypt requires --private-key (RSA) or --key (OpenPGP)" if key.nil?
+
         output = options[:output] || "#{File.basename(path_to_package, '.cap')}-decrypted.cap"
-        Capsium::Package::Cipher.new.decrypt(path_to_package, options[:private_key], output)
+        cipher = if options[:openpgp]
+                   Capsium::Package::OpenPgpCipher.new
+                 else
+                   Capsium::Package::Cipher.for_encrypted(path_to_package)
+                 end
+        cipher.decrypt(path_to_package, key, output)
         puts "Package decrypted: #{output}"
       end
 

data/lib/capsium/cli/reactor.rb

@@ -5,8 +5,9 @@ module Capsium
     class Reactor < Thor
       extend ThorExt::Start
 
-      desc "serve PACKAGE_PATH",
-           "Start the Capsium reactor to serve the package"
+      desc "serve PACKAGE_PATH ...",
+           "Start the Capsium reactor to serve one or more packages " \
+           "(local packages, or capsium:// GUIDs installed from a registry)"
       option :port, type: :numeric, default: Capsium::Reactor::DEFAULT_PORT
       option :do_not_listen, type: :boolean, default: false
       option :store, type: :string,
@@ -15,18 +16,123 @@ module Capsium
       option :deploy, type: :string,
                       desc: "deploy.json with reactor-side secrets " \
                             "(default: CAPSIUM_DEPLOY)"
+      option :registry, type: :string,
+                        desc: "Registry directory or https base URL for " \
+                              "capsium:// GUIDs and dependency fallback " \
+                              "(default: CAPSIUM_REGISTRY)"
+      option :constraint, type: :string, default: "*",
+                          desc: "Semver constraint for a capsium:// GUID"
+      option :mount, type: :array,
+                     desc: "Mount a source at a URL prefix, PATH=SOURCE " \
+                           "(repeatable; sources without a prefix default " \
+                           "to / for the first and /<name>/ for the rest)"
+      option :config, type: :string,
+                      desc: "JSON mount config: " \
+                            '{"mounts": [{"path": "/", "source": "...", "store": "..."}]}'
+      option :workdir, type: :string,
+                       desc: "Reactor work directory for writable overlays " \
+                             "and saved packages (default: a temporary directory)"
 
-      def serve(path_to_package)
+      # Thor array options are last-wins when the flag repeats; collect
+      # every --mount value (both "--mount V" and "--mount=V" forms)
+      # and re-emit one trailing occurrence so repetition accumulates.
+      # (Subcommands are dispatched in-process, so this hooks dispatch,
+      # not start; merging is idempotent for the direct-start flow.)
+      def self.dispatch(meth, given_args, given_opts, config)
+        super(meth, merge_mount_options(given_args),
+              given_opts && merge_mount_options(given_opts), config)
+      end
+
+      def self.merge_mount_options(args)
+        values = []
+        rest = []
+        index = 0
+        while index < args.length
+          arg = args[index]
+          if arg == "--mount"
+            index += 1
+            while index < args.length && !args[index].start_with?("-")
+              values << args[index]
+              index += 1
+            end
+          elsif arg.start_with?("--mount=")
+            values << arg.split("=", 2).last
+            index += 1
+          else
+            rest << arg
+            index += 1
+          end
+        end
+        values.empty? ? args : rest + ["--mount"] + values
+      end
+
+      def serve(*sources)
+        entries = mount_entries(sources)
+        if entries.empty?
+          raise Thor::Error, "no package source given (positional " \
+                             "arguments, --mount or --config)"
+        end
+
+        mounts = Capsium::Reactor::Mount.build(
+          entries, store: options[:store], registry: options[:registry]
+        )
         reactor = Capsium::Reactor.new(
-          package: path_to_package,
+          mounts: mounts,
           port: options[:port],
           do_not_listen: options[:do_not_listen],
           store: options[:store],
-          deploy: options[:deploy]
+          deploy: options[:deploy],
+          registry: options[:registry],
+          workdir: options[:workdir]
         )
         reactor.serve
+      rescue Capsium::Error => e
+        raise Thor::Error, e.message
       ensure
-        reactor&.package&.cleanup
+        reactor&.cleanup
+      end
+
+      private
+
+      # The combined mount entries from --config, --mount and the
+      # positional sources (in that order), with capsium:// GUIDs
+      # installed from the registry into the store.
+      def mount_entries(sources)
+        entries = []
+        entries.concat(Capsium::Reactor::Mount.config_entries(options[:config])) if options[:config]
+        entries.concat(Array(options[:mount]).map do |spec|
+          Capsium::Reactor::Mount.parse_spec(spec)
+        end)
+        entries.concat(sources.map do |source|
+          Capsium::Reactor::Mount::Entry.new(path: nil, source: source, store: nil)
+        end)
+        entries.map do |entry|
+          entry.with(source: resolve_source(entry.source))
+        end
+      end
+
+      def resolve_source(source)
+        return source unless source.start_with?("capsium://")
+
+        install_from_registry(source)
+      end
+
+      # Install-then-serve for capsium:// GUIDs: resolve and install
+      # from the registry into the package store, returning the
+      # installed store .cap path.
+      def install_from_registry(guid)
+        registry = Capsium::Registry.fetch(options[:registry] || ENV.fetch("CAPSIUM_REGISTRY", nil))
+        store = options[:store] || ENV.fetch("CAPSIUM_STORE", nil)
+        if store.nil? || store.empty?
+          raise Thor::Error,
+                "no package store configured (pass --store or set CAPSIUM_STORE)"
+        end
+
+        path = registry.install(guid, options[:constraint], store: store)
+        puts "Installed #{guid} to #{path}"
+        path
+      rescue Capsium::Registry::RegistryError => e
+        raise Thor::Error, e.message
       end
     end
   end

data/lib/capsium/cli.rb

@@ -19,5 +19,34 @@ module Capsium
 
     desc "convert SUBCOMMAND ...ARGS", "Convert from another format"
     subcommand "convert", Capsium::Cli::Convert
+
+    desc "install GUID", "Install a package from a registry into the package store"
+    option :constraint, type: :string, default: "*",
+                        desc: "Semver constraint the installed version must satisfy"
+    option :registry, type: :string,
+                      desc: "Registry directory or https base URL " \
+                            "(default: CAPSIUM_REGISTRY)"
+    option :store, type: :string,
+                   desc: "Package store directory (default: CAPSIUM_STORE)"
+
+    def install(guid)
+      registry = Capsium::Registry.fetch(options[:registry] || ENV.fetch("CAPSIUM_REGISTRY", nil))
+      path = registry.install(guid, options[:constraint], store: store_dir!)
+      puts "Installed #{guid} to #{path}"
+    rescue Capsium::Registry::RegistryError => e
+      raise Thor::Error, e.message
+    end
+
+    private
+
+    # The store directory for install-like commands: --store or
+    # CAPSIUM_STORE, otherwise a typed CLI error.
+    def store_dir!
+      store = options[:store] || ENV.fetch("CAPSIUM_STORE", nil)
+      return store unless store.nil? || store.empty?
+
+      raise Thor::Error,
+            "no package store configured (pass --store or set CAPSIUM_STORE)"
+    end
   end
 end

data/lib/capsium/log_buffer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Capsium
+  # A small thread-safe ring buffer of timestamped log entries with a
+  # fixed capacity: when full, the oldest entry is dropped. The reactor
+  # records key serving events here and exposes the most recent lines
+  # through the /package/:id/logs introspection endpoint.
+  class LogBuffer
+    DEFAULT_CAPACITY = 500
+
+    # One buffer entry: a UTC timestamp and a message.
+    Entry = Data.define(:timestamp, :message) do
+      # "2026-07-19T15:00:00Z message"
+      def line = "#{timestamp.utc.iso8601} #{message}"
+    end
+
+    attr_reader :capacity
+
+    def initialize(capacity: DEFAULT_CAPACITY)
+      raise ArgumentError, "capacity must be at least 1" if capacity < 1
+
+      @capacity = capacity
+      @entries = []
+      @mutex = Mutex.new
+    end
+
+    def add(message, timestamp: Time.now)
+      @mutex.synchronize do
+        @entries.shift if @entries.size >= @capacity
+        @entries << Entry.new(timestamp: timestamp, message: message)
+      end
+      self
+    end
+
+    # The last count entries, oldest first.
+    def last(count)
+      @mutex.synchronize { @entries.last(count) }
+    end
+
+    # The last count entries as formatted lines, oldest first.
+    def lines(count)
+      last(count).map(&:line)
+    end
+  end
+end

data/lib/capsium/package/bundle.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "zip"
+
+module Capsium
+  class Package
+    # Bundled dependencies of an encapsulated (self-contained) package
+    # (ARCHITECTURE.md section 4a extension): dependency .cap files
+    # embedded under packages/ with a packages/index.json manifest
+    # mapping each dependency GUID to its file, version and SHA-256:
+    #
+    #   packages/
+    #     index.json                # guid => {"file", "version", "sha256"}
+    #     <name>-<version>.cap      # one per declared dependency
+    #
+    # One-level bundling policy: only the dependencies DECLARED in the
+    # package's own metadata.dependencies are bundled; to make a whole
+    # tree self-contained the parent must declare the transitive
+    # closure. At load time bundled dependencies resolve FIRST, before
+    # the store -> registry chain, and a package's bundle is passed down
+    # to its dependencies so their re-declared dependencies resolve from
+    # it too (recursive-capable).
+    #
+    # Security: bundled .cap files are covered by the parent package's
+    # security.json checksums like every other file; the manifest
+    # SHA-256 is re-verified when a bundled dependency is resolved, and
+    # each bundled package's own security.json is verified when it is
+    # loaded (the usual Capsium::Package activation checks).
+    class Bundle
+      DIRECTORY = "packages"
+      INDEX_FILE = "packages/index.json"
+
+      # One bundled dependency: the absolute .cap path, its version and
+      # the SHA-256 recorded in the manifest.
+      Entry = Data.define(:file, :version, :sha256)
+
+      attr_reader :entries
+
+      def initialize(package_path, entries = nil)
+        @entries = entries || load_entries(package_path)
+      end
+
+      # Embeds the resolved dependency .cap files (guid => .cap path
+      # pairs, in declaration order) into the package directory at
+      # package_path: copies each under packages/ and writes the
+      # packages/index.json manifest. Returns the manifest hash.
+      def self.write(package_path, resolutions)
+        FileUtils.mkdir_p(File.join(package_path, DIRECTORY))
+        index = resolutions.to_h do |guid, cap_path|
+          file = File.join(DIRECTORY, File.basename(cap_path))
+          FileUtils.cp(cap_path, File.join(package_path, file))
+          [guid, { "file" => file,
+                   "version" => cap_version(cap_path),
+                   "sha256" => Digest::SHA256.file(cap_path).hexdigest }]
+        end
+        File.write(File.join(package_path, INDEX_FILE), JSON.pretty_generate(index))
+        index
+      end
+
+      def self.cap_version(cap_path)
+        Zip::File.open(cap_path) do |zip|
+          entry = zip.find_entry(METADATA_FILE)
+          raise DependencyError, "no #{METADATA_FILE} in #{cap_path}" unless entry
+
+          JSON.parse(entry.get_input_stream.read)["version"].to_s
+        end
+      end
+      private_class_method :cap_version
+
+      # Whether this bundle embeds any dependency.
+      def present? = !@entries.empty?
+
+      # Merges an inherited (ancestor) bundle underneath this one; own
+      # entries win on GUID conflicts. Entries carry absolute paths, so
+      # merged entries keep pointing into their source packages.
+      def merged_with(other)
+        return self if other.nil? || !other.present?
+        return other unless present?
+
+        self.class.new(nil, other.entries.merge(@entries))
+      end
+
+      # The absolute .cap path for a bundled dependency, or nil when the
+      # GUID is not bundled (the caller falls back to the store ->
+      # registry chain). Raises CircularDependencyError when the GUID is
+      # already being resolved up-chain, UnsatisfiableDependencyError
+      # when the bundled version does not satisfy the declared range and
+      # Security::IntegrityError when the bundled file fails the
+      # manifest SHA-256.
+      def resolve_path(guid, range, chain:)
+        entry = @entries[guid]
+        return nil if entry.nil?
+
+        if chain.include?(guid)
+          raise CircularDependencyError,
+                "circular dependency: #{(chain + [guid]).join(' -> ')}"
+        end
+
+        unless VersionRange.parse(range).satisfied_by?(Version.parse(entry.version))
+          raise UnsatisfiableDependencyError,
+                "bundled #{guid} #{entry.version} does not satisfy '#{range}'"
+        end
+
+        verify_sha256(guid, entry)
+        entry.file
+      end
+
+      private
+
+      def verify_sha256(guid, entry)
+        actual = Digest::SHA256.file(entry.file).hexdigest
+        return if actual == entry.sha256
+
+        raise Security::IntegrityError,
+              "bundled package failed manifest SHA-256 verification: " \
+              "#{guid} (#{entry.file})"
+      end
+
+      def load_entries(package_path)
+        index_path = File.join(package_path, INDEX_FILE)
+        return {} unless File.file?(index_path)
+
+        JSON.parse(File.read(index_path)).to_h do |guid, entry|
+          [guid, Entry.new(file: File.join(package_path, entry.fetch("file")),
+                           version: entry.fetch("version"),
+                           sha256: entry.fetch("sha256"))]
+        end
+      rescue JSON::ParserError, KeyError => e
+        raise DependencyError, "invalid #{INDEX_FILE}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/capsium/package/cipher.rb

@@ -30,8 +30,10 @@ module Capsium
     #
     # A random 256-bit data encryption key (DEK) encrypts the inner zip;
     # the DEK is wrapped with the recipient's RSA public key using OAEP
-    # with SHA-256 (MGF1-SHA-256). The OCB/OpenPGP alternatives mentioned
-    # by the standard are intentionally out of scope.
+    # with SHA-256 (MGF1-SHA-256). OpenPGP key management (an armored
+    # OpenPGP message carrying the DEK) is provided by the parallel
+    # OpenPgpCipher subclass; the OCB alternative mentioned by the
+    # standard remains out of scope.
     class Cipher
       ALGORITHM = "AES-256-GCM"
       KEY_MANAGEMENT = "RSA-OAEP-SHA256"
@@ -61,6 +63,33 @@ module Capsium
         false
       end
 
+      # The keyManagement declared by the encryption envelope of the
+      # path (.cap file or uncompressed directory), or nil when the
+      # envelope is absent or unreadable.
+      def self.key_management(path)
+        source = envelope_source(path)
+        source && EncryptionConfig.from_json(source).encryption&.key_management
+      rescue Lutaml::Model::Error, JSON::ParserError
+        nil
+      end
+
+      # The cipher instance matching the envelope's keyManagement:
+      # OpenPgpCipher for OpenPGP envelopes, the RSA cipher otherwise.
+      def self.for_encrypted(path)
+        key_management(path) == OpenPgpCipher::KEY_MANAGEMENT ? OpenPgpCipher.new : new
+      end
+
+      def self.envelope_source(path)
+        envelope = File.join(path, ENVELOPE_FILE)
+        return File.read(envelope) if File.directory?(path) && File.file?(envelope)
+        return nil if File.directory?(path)
+
+        Zip::File.open(path) { |zip| zip.find_entry(ENVELOPE_FILE)&.get_input_stream&.read }
+      rescue Errno::ENOENT, Zip::Error
+        nil
+      end
+      private_class_method :envelope_source
+
       # Encrypts the package at source_path (a .cap file, or a package
       # directory which is packed first) for the recipient's RSA public
       # key (or X.509 certificate) and writes the encrypted .cap to
@@ -87,11 +116,14 @@ module Capsium
       end
 
       # Decrypts an encrypted package into a fresh temporary directory
-      # and returns the directory path.
+      # and returns the directory path. The cipher is selected from the
+      # envelope's keyManagement (for_encrypted), so
+      # Package.new(decryption_key:) accepts either key format
+      # transparently.
       def self.decrypt_to_directory(source_path, private_key_path)
         Dir.mktmpdir.tap do |tmp|
           inner_cap = File.join(tmp, "inner.cap")
-          new.decrypt(source_path, private_key_path, inner_cap)
+          for_encrypted(source_path).decrypt(source_path, private_key_path, inner_cap)
           package_path = File.join(tmp, File.basename(source_path.to_s, ".cap"))
           FileUtils.mkdir_p(package_path)
           Packager.new.unpack(inner_cap, package_path)
@@ -117,29 +149,51 @@ module Capsium
         cipher = OpenSSL::Cipher.new(ALGORITHM.downcase)
         cipher.encrypt
         dek = cipher.random_key
-        iv = cipher.random_iv
+        gcm_iv = cipher.random_iv
         ciphertext = cipher.update(plaintext) + cipher.final
-        envelope = EncryptionEnvelope.new(
-          algorithm: ALGORITHM, key_management: KEY_MANAGEMENT,
-          encrypted_dek: Base64.strict_encode64(public_key.encrypt(dek, RSA_OPTIONS)),
-          iv: Base64.strict_encode64(iv), auth_tag: Base64.strict_encode64(cipher.auth_tag)
+        [envelope_for(dek, gcm_iv, cipher.auth_tag, public_key), ciphertext]
+      end
+
+      # The encryption envelope carrying the DEK protected for the
+      # recipient (RSA-OAEP-SHA256 wrapped here; OpenPgpCipher overrides
+      # this with an OpenPGP message). The subclass seam for key
+      # management; ALGORITHM/iv/authTag stay as-is.
+      def envelope_for(dek, gcm_iv, auth_tag, public_key)
+        EncryptionConfig.new(
+          encryption: EncryptionEnvelope.new(
+            algorithm: ALGORITHM, key_management: KEY_MANAGEMENT,
+            encrypted_dek: Base64.strict_encode64(public_key.encrypt(dek, RSA_OPTIONS)),
+            iv: Base64.strict_encode64(gcm_iv), auth_tag: Base64.strict_encode64(auth_tag)
+          )
         )
-        [EncryptionConfig.new(encryption: envelope), ciphertext]
       end
 
       def decrypt_bytes(ciphertext, envelope, private_key)
-        dek = private_key.decrypt(Base64.strict_decode64(envelope.encrypted_dek), RSA_OPTIONS)
+        dek = unwrap_dek(envelope, private_key)
+        gcm_decrypt(ciphertext, dek, envelope)
+      rescue ArgumentError
+        raise CipherError, "invalid Base64 in the encryption envelope"
+      end
+
+      # Recovers the DEK from the envelope (RSA-OAEP-SHA256 unwrap here;
+      # OpenPgpCipher overrides this with an OpenPGP decryption).
+      def unwrap_dek(envelope, private_key)
+        private_key.decrypt(Base64.strict_decode64(envelope.encrypted_dek), RSA_OPTIONS)
+      rescue OpenSSL::PKey::PKeyError
+        # DEK unwrap failure (wrong key or a malformed envelope).
+        raise DecryptionError, "decryption failed: wrong key or tampered package"
+      end
+
+      def gcm_decrypt(ciphertext, dek, envelope)
         cipher = OpenSSL::Cipher.new(ALGORITHM.downcase)
         cipher.decrypt
         cipher.key = dek
         cipher.iv = Base64.strict_decode64(envelope.iv)
         cipher.auth_tag = Base64.strict_decode64(envelope.auth_tag)
         cipher.update(ciphertext) + cipher.final
-      rescue ArgumentError
-        raise CipherError, "invalid Base64 in the encryption envelope"
-      rescue OpenSSL::PKey::PKeyError, OpenSSL::Cipher::CipherError
-        # DEK unwrap failure or GCM tag verification failure (wrong key
-        # or tampered ciphertext), or a malformed envelope iv/authTag.
+      rescue OpenSSL::Cipher::CipherError
+        # GCM tag verification failure (wrong key or tampered
+        # ciphertext), or a malformed envelope iv/authTag.
         raise DecryptionError, "decryption failed: wrong key or tampered package"
       end
 
@@ -162,7 +216,9 @@ module Capsium
       end
 
       def supported_envelope?(envelope)
-        [envelope.algorithm, envelope.key_management] == [ALGORITHM, KEY_MANAGEMENT]
+        # self.class:: so subclasses (OpenPgpCipher) match their own
+        # KEY_MANAGEMENT despite Ruby's lexical constant lookup.
+        [envelope.algorithm, envelope.key_management] == [ALGORITHM, self.class::KEY_MANAGEMENT]
       end
 
       def read_source(path, entry_name)