capsium 0.2.0 → 0.6.0

data/capsium.gemspec

@@ -33,12 +33,15 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 3.2.0"
 
+  spec.add_dependency "bcrypt"
   spec.add_dependency "csv"
+  spec.add_dependency "graphql"
   spec.add_dependency "json"
   spec.add_dependency "json-schema"
   spec.add_dependency "listen"
   spec.add_dependency "lutaml-model", ">= 0.8", "< 1.0"
   spec.add_dependency "marcel"
+  spec.add_dependency "rnp", ">= 1.0"
   spec.add_dependency "rubyzip", ">= 2.3.2", "< 4.0"
   spec.add_dependency "sqlite3"
   spec.add_dependency "thor"

data/lib/capsium/cli/formatting.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Cli < Thor
+    # Output formatting helpers for CLI subcommands.
+    module Formatting
+      private
+
+      def format_result(result)
+        line = "#{result.ok? ? 'PASS' : 'FAIL'} #{result.name}"
+        return line if result.messages.empty?
+
+        "#{line}: #{result.messages.join('; ')}"
+      end
+
+      # The resolved dependency tree (ARCHITECTURE.md section 4a): one
+      # line per dependency showing the declared GUID and range, the
+      # resolved version and the store .cap it resolved to, nested.
+      def print_dependency_tree(package, indent = "")
+        package.resolved_dependencies.each do |dep|
+          puts "#{indent}- #{dep.guid} (#{dep.range}) => #{dep.version} [#{dep.path}]"
+          print_dependency_tree(dep.package, "#{indent}  ")
+        end
+      end
+    end
+  end
+end

data/lib/capsium/cli/package.rb

@@ -6,14 +6,17 @@ module Capsium
   class Cli
     class Package < Thor
       extend ThorExt::Start
+      include Formatting
 
       desc "info PACKAGE_PATH", "Display information about the package"
+      option :store, type: :string, desc: "Package store directory (default: CAPSIUM_STORE)"
 
       def info(path_to_package)
-        package = Capsium::Package.new(path_to_package)
+        package = Capsium::Package.new(path_to_package, store: options[:store])
         puts "Package Path: #{package.path}"
         puts "Routes: #{package.routes.to_hash}"
         puts "Manifest: #{package.manifest.to_hash}"
+        print_dependency_tree(package)
       end
 
       desc "manifest PATH_TO_PACKAGE",
@@ -47,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
@@ -63,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)
@@ -73,13 +93,92 @@ module Capsium
         raise Thor::Error, "Package validation failed"
       end
 
-      private
+      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: "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)
+        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-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 format_result(result)
-        line = "#{result.ok? ? 'PASS' : 'FAIL'} #{result.name}"
-        return line if result.messages.empty?
+      def verify_signature(path_to_package)
+        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
 
-        "#{line}: #{result.messages.join('; ')}"
+        puts "Signature valid: #{path_to_package}"
+      rescue Capsium::Package::Signer::SignatureError => e
+        raise Thor::Error, e.message
+      end
+
+      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)
+        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 | --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"
+        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
+
+      desc "test PACKAGE_PATH", "Run the package's tests/*.yaml suite (05x-testing DSL)"
+
+      def test(path_to_package)
+        package = Capsium::Package.new(path_to_package)
+        report = Capsium::Package::Testing::TestSuite.new(package).run
+        report.results.each { |result| puts format_result(result) }
+        if report.results.empty?
+          puts "No tests found (#{Capsium::Package::Testing::TestSuite::TESTS_DIR}/*.yaml)"
+        end
+        puts report.summary
+        raise Thor::Error, "Package tests failed" unless report.ok?
       end
     end
   end

data/lib/capsium/cli/reactor.rb

@@ -5,20 +5,134 @@ 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,
+                     desc: "Package store directory for dependency " \
+                           "resolution (default: CAPSIUM_STORE)"
+      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]
+          do_not_listen: options[:do_not_listen],
+          store: options[:store],
+          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

@@ -7,6 +7,7 @@ module Capsium
     extend ThorExt::Start
 
     autoload :Convert, "capsium/cli/convert"
+    autoload :Formatting, "capsium/cli/formatting"
     autoload :Package, "capsium/cli/package"
     autoload :Reactor, "capsium/cli/reactor"
 
@@ -18,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/authentication.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Capsium
+  class Package
+    # Loads a package's authentication.json (ARCHITECTURE.md section 4b).
+    class Authentication
+      extend Forwardable
+
+      attr_reader :path, :config
+
+      def_delegators :@config, :to_json, :to_hash
+
+      def initialize(path)
+        @path = path
+        @config = File.exist?(path) ? AuthenticationConfig.from_json(File.read(path)) : nil
+      end
+
+      def present?
+        !@config.nil?
+      end
+
+      def basic_auth
+        @config&.authentication&.basic_auth
+      end
+
+      def oauth2
+        @config&.authentication&.oauth2
+      end
+
+      # Whether any authentication method is enabled.
+      def enabled?
+        !!(basic_auth&.enabled? || oauth2&.enabled?)
+      end
+    end
+  end
+end

data/lib/capsium/package/authentication_config.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "json"
+require "lutaml/model"
+
+module Capsium
+  class Package
+    # The "basicAuth" object of authentication.json (ARCHITECTURE.md
+    # section 4b): Apache-style Basic authentication verified against an
+    # htpasswd file. "passwdFile" is a package-relative path (password
+    # hashes, not plaintext secrets, so it may ship in the package);
+    # deploy.json may override it with a reactor-side file.
+    class BasicAuthConfig < Lutaml::Model::Serializable
+      attribute :enabled, :boolean, default: false
+      attribute :passwd_file, :string
+      attribute :realm, :string, default: "capsium"
+
+      json do
+        map :enabled, to: :enabled
+        map "passwdFile", to: :passwd_file
+        map :realm, to: :realm
+      end
+
+      def enabled?
+        !!enabled
+      end
+    end
+
+    # The "oauth2" object of authentication.json: an OAuth2
+    # authorization-code flow. The client secret is NEVER read from the
+    # package — it comes from deploy.json or reactor configuration.
+    class OAuth2Config < Lutaml::Model::Serializable
+      attribute :enabled, :boolean, default: false
+      attribute :provider, :string
+      attribute :client_id, :string
+      attribute :authorization_url, :string
+      attribute :token_url, :string
+      attribute :userinfo_url, :string
+      attribute :redirect_path, :string, default: "/auth/callback"
+      attribute :scopes, :string, collection: true, default: []
+
+      json do
+        map :enabled, to: :enabled
+        map :provider, to: :provider
+        map "clientId", to: :client_id
+        map "authorizationUrl", to: :authorization_url
+        map "tokenUrl", to: :token_url
+        map "userinfoUrl", to: :userinfo_url
+        map "redirectPath", to: :redirect_path
+        map :scopes, to: :scopes
+      end
+
+      def enabled?
+        !!enabled
+      end
+    end
+
+    # The "authentication" object of authentication.json.
+    class AuthenticationData < Lutaml::Model::Serializable
+      attribute :basic_auth, BasicAuthConfig
+      attribute :oauth2, OAuth2Config
+
+      json do
+        map "basicAuth", to: :basic_auth
+        map :oauth2, to: :oauth2
+      end
+    end
+
+    # Canonical authentication.json model (ARCHITECTURE.md section 4b).
+    class AuthenticationConfig < Lutaml::Model::Serializable
+      attribute :authentication, AuthenticationData
+
+      json do
+        map :authentication, to: :authentication
+      end
+    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