capsium 0.2.0 → 0.6.0

data/lib/capsium/package/cipher.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "base64"
+require "fileutils"
+require "json"
+require "openssl"
+require "tmpdir"
+require "zip"
+
+module Capsium
+  class Package
+    # Encrypts and decrypts whole Capsium packages (05x-packaging
+    # "Encryption", 05x-security "Encrypted information").
+    #
+    # An encrypted .cap is a zip containing exactly:
+    #
+    #   metadata.json   (cleartext, per the standard: name/version stay
+    #                    readable without the key)
+    #   signature.json  (the encryption envelope)
+    #   package.enc     (AES-256-GCM ciphertext of the inner, plaintext
+    #                    .cap zip holding content/, the configuration
+    #                    files and data/)
+    #
+    # The envelope:
+    #
+    #   {"encryption": {"algorithm": "AES-256-GCM",
+    #                   "keyManagement": "RSA-OAEP-SHA256",
+    #                   "encryptedDek": <base64>, "iv": <base64>,
+    #                   "authTag": <base64>}}
+    #
+    # 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). 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"
+      ENCRYPTED_FILE = "package.enc"
+      ENVELOPE_FILE = "signature.json"
+      RSA_OPTIONS = { "rsa_padding_mode" => "oaep",
+                      "rsa_oaep_md" => "SHA256", "rsa_mgf1_md" => "SHA256" }.freeze
+
+      # Structural problems: unreadable input, missing zip entries,
+      # unsupported envelope algorithms, unloadable keys.
+      class CipherError < Capsium::Error; end
+
+      # An encrypted package was opened without a private key.
+      class KeyRequiredError < CipherError; end
+
+      # Decryption failed: wrong private key or tampered ciphertext.
+      class DecryptionError < CipherError; end
+
+      # Whether the path (.cap file or uncompressed directory) is an
+      # encrypted package, i.e. contains package.enc.
+      def self.encrypted?(path)
+        return File.file?(File.join(path, ENCRYPTED_FILE)) if File.directory?(path)
+        return false unless File.file?(path)
+
+        Zip::File.open(path) { |zip| !zip.find_entry(ENCRYPTED_FILE).nil? }
+      rescue Zip::Error
+        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
+      # output_path.
+      def encrypt(source_path, public_key_path, output_path)
+        public_key = load_public_key(public_key_path)
+        with_cap_file(source_path) do |cap_path|
+          envelope, ciphertext = encrypt_bytes(File.binread(cap_path), public_key)
+          write_encrypted_cap(output_path, read_source(cap_path, Package::METADATA_FILE),
+                              envelope, ciphertext)
+        end
+        output_path
+      end
+
+      # Decrypts the encrypted package at encrypted_path (.cap file or
+      # uncompressed directory) with the recipient's RSA private key and
+      # writes the plaintext .cap to output_path.
+      def decrypt(encrypted_path, private_key_path, output_path)
+        private_key = load_private_key(private_key_path)
+        envelope = load_envelope(encrypted_path)
+        ciphertext = read_source(encrypted_path, ENCRYPTED_FILE)
+        File.binwrite(output_path, decrypt_bytes(ciphertext, envelope, private_key))
+        output_path
+      end
+
+      # Decrypts an encrypted package into a fresh temporary directory
+      # 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")
+          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)
+          FileUtils.rm_f(inner_cap)
+          return package_path
+        end
+      end
+
+      private
+
+      def with_cap_file(source_path)
+        return yield source_path if File.file?(source_path) && File.extname(source_path) == ".cap"
+        raise CipherError, "cannot encrypt: #{source_path}" unless File.directory?(source_path)
+
+        Dir.mktmpdir do |dir|
+          cap_path = File.join(dir, "inner.cap")
+          Packager.new.compress_package(Capsium::Package.new(source_path), cap_path)
+          yield cap_path
+        end
+      end
+
+      def encrypt_bytes(plaintext, public_key)
+        cipher = OpenSSL::Cipher.new(ALGORITHM.downcase)
+        cipher.encrypt
+        dek = cipher.random_key
+        gcm_iv = cipher.random_iv
+        ciphertext = cipher.update(plaintext) + cipher.final
+        [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)
+          )
+        )
+      end
+
+      def decrypt_bytes(ciphertext, envelope, private_key)
+        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 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
+
+      def write_encrypted_cap(output_path, metadata_json, envelope, ciphertext)
+        FileUtils.rm_f(output_path)
+        Zip::File.open(output_path, create: true) do |zip|
+          zip.get_output_stream(Package::METADATA_FILE) { |stream| stream.write(metadata_json) }
+          zip.get_output_stream(ENVELOPE_FILE) { |stream| stream.write(envelope.to_json) }
+          zip.get_output_stream(ENCRYPTED_FILE) { |stream| stream.write(ciphertext) }
+        end
+      end
+
+      def load_envelope(encrypted_path)
+        envelope = EncryptionConfig.from_json(read_source(encrypted_path, ENVELOPE_FILE)).encryption
+        return envelope if envelope && supported_envelope?(envelope)
+
+        raise CipherError, "missing or unsupported encryption envelope in: #{encrypted_path}"
+      rescue Lutaml::Model::Error, JSON::ParserError => e
+        raise CipherError, "invalid encryption envelope in #{encrypted_path}: #{e.message}"
+      end
+
+      def supported_envelope?(envelope)
+        # 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)
+        return File.binread(File.join(path, entry_name)) if File.directory?(path)
+
+        Zip::File.open(path) do |zip|
+          entry = zip.find_entry(entry_name)
+          raise CipherError, "entry missing in #{path}: #{entry_name}" unless entry
+
+          return entry.get_input_stream.read
+        end
+      rescue Errno::ENOENT, Zip::Error => e
+        raise CipherError, "cannot read #{entry_name} in #{path}: #{e.message}"
+      end
+
+      def load_public_key(public_key_path)
+        pem = File.read(public_key_path)
+        OpenSSL::PKey::RSA.new(pem)
+      rescue OpenSSL::PKey::PKeyError
+        OpenSSL::X509::Certificate.new(pem).public_key
+      rescue OpenSSL::X509::CertificateError, Errno::ENOENT
+        raise CipherError, "cannot load public key or certificate: #{public_key_path}"
+      end
+
+      def load_private_key(private_key_path)
+        OpenSSL::PKey::RSA.new(File.read(private_key_path))
+      rescue OpenSSL::PKey::PKeyError, Errno::ENOENT
+        raise CipherError, "cannot load private key: #{private_key_path}"
+      end
+    end
+  end
+end

data/lib/capsium/package/composition.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # Composite-package support (ARCHITECTURE.md section 4a), mixed into
+    # Package: metadata.dependencies resolution — bundled dependencies
+    # (Capsium::Package::Bundle) first, then the package store — and
+    # load-time validation of dependency resource references.
+    module Composition
+      private
+
+      # Resolves metadata.dependencies: bundled dependencies first
+      # (Capsium::Package::Bundle — encapsulated packages embed their
+      # dependencies under packages/, so they activate with no store or
+      # registry), then the store (the `store` argument, else
+      # CAPSIUM_STORE) with the given `registry` (else CAPSIUM_REGISTRY)
+      # as install fallback for store misses. The store resolver is only
+      # constructed when a dependency is not bundled, so a fully
+      # bundled package needs neither. Each resolved dependency loads
+      # recursively with an extended circularity chain and this
+      # package's bundle underneath its own (re-declared transitive
+      # dependencies resolve from it); its exported content becomes
+      # lower read-only layers of this package's merged view.
+      def resolve_dependencies(store, registry, chain, bundle = nil)
+        declared = @metadata.dependencies
+        return [] if declared.empty?
+
+        chain += [@metadata.guid]
+        bundle = Bundle.new(@path).merged_with(bundle)
+        resolver = nil
+        declared.map do |guid, range|
+          cap_path = bundle.resolve_path(guid, range, chain: chain)
+          if cap_path.nil?
+            resolver ||= DependencyResolver.new(store || Store.default, registry: registry)
+            cap_path = resolver.resolve_path(guid, range, chain: chain)
+          end
+          ResolvedDependency.new(
+            guid: guid, range: range, path: cap_path,
+            package: Package.new(cap_path,
+                                 store: resolver ? resolver.store : store,
+                                 registry: resolver ? resolver.registry : registry,
+                                 dependency_chain: chain,
+                                 bundle: bundle)
+          )
+        end
+      end
+
+      # Every route resource given as a URI ("<dependency-guid>/<path>")
+      # must address a resolved dependency and a resource that dependency
+      # exports; anything else is a load-time error (section 4a).
+      def validate_dependency_references!
+        @routes.config.routes.each do |route|
+          reference = route.resource
+          next unless route.dependency_reference?
+
+          dependency = dependency_for(reference)
+          unless dependency
+            raise DependencyError,
+                  "route #{route.path} references unknown dependency: #{reference}"
+          end
+
+          validate_dependency_reference(route, dependency, reference)
+        end
+      end
+
+      def validate_dependency_reference(route, dependency, reference)
+        inner = reference.delete_prefix("#{dependency.guid}/")
+        return if dependency.package.merged_view(exported_only: true).resolve(inner)
+
+        if dependency.package.merged_view.resolve(inner)
+          raise DependencyVisibilityError,
+                "route #{route.path} references a private resource of " \
+                "dependency #{dependency.guid}: #{inner}"
+        end
+        raise DependencyError,
+              "route #{route.path} references a resource missing from " \
+              "dependency #{dependency.guid}: #{inner}"
+      end
+
+      def dependency_for(reference)
+        @resolved_dependencies
+          .sort_by { |dependency| -dependency.guid.length }
+          .find { |dependency| reference.start_with?("#{dependency.guid}/") }
+      end
+
+      def dependency_views
+        @resolved_dependencies.map do |dependency|
+          [dependency.guid, dependency.package.merged_view(exported_only: true)]
+        end
+      end
+    end
+  end
+end

data/lib/capsium/package/dataset.rb

@@ -67,6 +67,26 @@ module Capsium
         problems
       end
 
+      # The parsed JSON schema for this dataset, or nil when none is
+      # declared or the file is unreadable.
+      def json_schema
+        return nil unless @config.schema_file && @config.schema_type == "json-schema"
+        return nil unless File.file?(schema_path)
+
+        load_schema
+      end
+
+      # Schema validation of an arbitrary candidate document (used by
+      # the reactor's writable overlay before persisting a mutation):
+      # human-readable schema problems, empty when valid or when the
+      # dataset has no JSON schema.
+      def schema_errors_for(data)
+        return [] unless @config.schema_file && @config.schema_type == "json-schema"
+        return [] unless File.file?(schema_path)
+
+        JSON::Validator.fully_validate(load_schema, JSON.parse(JSON.generate(data)))
+      end
+
       private
 
       def schema_validation_errors

data/lib/capsium/package/dependency_resolver.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # Base error for composite-package dependency resolution
+    # (ARCHITECTURE.md section 4a).
+    class DependencyError < Capsium::Error; end
+
+    # No package in the store provides the dependency GUID.
+    class DependencyNotFoundError < DependencyError; end
+
+    # The store provides the GUID but no version satisfies the range.
+    class UnsatisfiableDependencyError < DependencyError; end
+
+    # A dependency cycle was detected while resolving.
+    class CircularDependencyError < DependencyError; end
+
+    # A dependent route references a dependency resource that is not
+    # exported (private) and therefore not visible to dependents.
+    class DependencyVisibilityError < DependencyError; end
+
+    # One resolved dependency: the declared GUID and range, the .cap it
+    # resolved to and the loaded package.
+    ResolvedDependency = Data.define(:guid, :range, :path, :package) do
+      def version
+        package.metadata.version
+      end
+    end
+
+    # Orchestrates metadata.dependencies resolution against a package
+    # store: circularity checks plus store lookup, with a registry
+    # (Capsium::Registry) as install fallback for store misses.
+    # Package loads the resolved .cap itself (recursively, with an
+    # extended chain).
+    class DependencyResolver
+      attr_reader :store, :registry
+
+      def initialize(store, registry: nil)
+        if store.nil?
+          raise DependencyError,
+                "metadata.dependencies declared but no package store " \
+                "configured (set CAPSIUM_STORE or pass store:)"
+        end
+
+        @store = store.is_a?(Store) ? store : Store.new(store.to_s)
+        @registry = if registry.nil? || registry.is_a?(Capsium::Registry)
+                      registry
+                    else
+                      Capsium::Registry.fetch(registry)
+                    end
+        @registry ||= Capsium::Registry.default
+      end
+
+      # The newest store .cap satisfying the dependency. Falls back to
+      # installing from the configured registry when the store has no
+      # package for the GUID. Raises CircularDependencyError when the
+      # GUID is already being resolved up-chain,
+      # DependencyNotFoundError when neither the store nor a registry
+      # provides it and UnsatisfiableDependencyError when no available
+      # version satisfies the range.
+      def resolve_path(guid, range, chain:)
+        if chain.include?(guid)
+          raise CircularDependencyError,
+                "circular dependency: #{(chain + [guid]).join(' -> ')}"
+        end
+
+        @store.find(guid, range)
+      rescue DependencyNotFoundError => e
+        resolve_from_registry(guid, range, e)
+      end
+
+      private
+
+      # Registry fallback for store misses (fallback chain: store ->
+      # registry -> typed error). Installs the newest satisfying version
+      # into the store and returns its path; re-raises the store error
+      # when no registry is configured.
+      def resolve_from_registry(guid, range, store_error)
+        raise store_error if @registry.nil?
+
+        @registry.install(guid, range, store: @store)
+      rescue Registry::PackageNotFoundError
+        raise DependencyNotFoundError,
+              "#{store_error.message}; no package #{guid} in registry " \
+              "#{@registry.location} either"
+      rescue Registry::UnsatisfiableConstraintError => e
+        raise UnsatisfiableDependencyError, e.message
+      end
+    end
+  end
+end

data/lib/capsium/package/encryption_config.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Capsium
+  class Package
+    # The "encryption" object of signature.json in an encrypted package
+    # (05x-packaging "Encryption"): the AES-256-GCM envelope, all binary
+    # values Base64-encoded. keyManagement selects how the data
+    # encryption key (DEK) is protected: "RSA-OAEP-SHA256" carries it in
+    # encryptedDek (RSA-wrapped); "OpenPGP" carries an armored OpenPGP
+    # message containing the DEK in message.
+    class EncryptionEnvelope < Lutaml::Model::Serializable
+      attribute :algorithm, :string
+      attribute :key_management, :string
+      attribute :encrypted_dek, :string
+      attribute :message, :string
+      attribute :iv, :string
+      attribute :auth_tag, :string
+
+      json do
+        map :algorithm, to: :algorithm
+        map "keyManagement", to: :key_management
+        map "encryptedDek", to: :encrypted_dek
+        map :message, to: :message
+        map :iv, to: :iv
+        map "authTag", to: :auth_tag
+      end
+    end
+
+    # The signature.json file of an encrypted package. In this phase it
+    # carries only the encryption envelope (digital signatures over
+    # encrypted packages are a later phase).
+    class EncryptionConfig < Lutaml::Model::Serializable
+      attribute :encryption, EncryptionEnvelope
+
+      json do
+        map :encryption, to: :encryption
+      end
+    end
+  end
+end

data/lib/capsium/package/manifest.rb

@@ -71,7 +71,7 @@ module Capsium
       private
 
       def content_files
-        Dir.glob(File.join(@content_path, "**", "*")).select do |file|
+        Dir.glob(File.join(@content_path, "**", "*"), File::FNM_DOTMATCH).select do |file|
           File.file?(file)
         end
       end

data/lib/capsium/package/merged_view.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Capsium
+  class Package
+    # The merged (overlay) view of a package's content, per ARCHITECTURE.md
+    # section 5a. Shared by Package (validation) and Reactor (serving).
+    #
+    # The content/ tree is always the implicit bottom layer; layers from
+    # storage.layers stack on top of it, bottom -> top in declaration
+    # order. Resolution scans from the TOP down and the first hit wins.
+    # Deletions are recorded as tombstones: a `.capsium-tombstones` JSON
+    # file in a writable layer listing content/-relative paths; a
+    # tombstoned path resolves to nil even when a lower layer (including a
+    # dependency's content) holds the file, while a file reappearing in a
+    # layer ABOVE the tombstone is served again.
+    #
+    # Composite packages (section 4a): `dependency_views` are
+    # [dependency GUID, MergedView] pairs acting as read-only layers below
+    # ALL own layers. A resource reference that is a URI of the form
+    # "<dependency-guid>/<path>" resolves explicitly against that
+    # dependency's view; plain content paths fall through to the
+    # dependency layers in declaration order after all own layers miss.
+    #
+    # With `exported_only: true` (the view a dependent package gets):
+    # layers whose visibility is "private" are hidden entirely, and a path
+    # resolves only when the manifest lists the resource as "exported".
+    # `extra_layers` stack on top of ALL own layers (e.g. the reactor's
+    # writable overlay, section 5a).
+    class MergedView
+      # A single read layer: an absolute root directory mirroring the
+      # content/ tree, plus its parsed tombstone set.
+      Layer = Data.define(:root, :visibility, :tombstones) do
+        def file?(content_relative_path)
+          File.file?(absolute(content_relative_path))
+        end
+
+        def absolute(content_relative_path)
+          File.join(root, content_relative_path)
+        end
+      end
+
+      TOMBSTONE_FILE = ".capsium-tombstones"
+      CONTENT_PREFIX = "#{Package::CONTENT_DIR}/".freeze
+
+      attr_reader :package_path, :layers, :dependency_views
+
+      def initialize(package_path, storage:, manifest:, dependency_views: [],
+                     exported_only: false, extra_layers: [])
+        @package_path = package_path
+        @storage = storage
+        @manifest = manifest
+        @exported_only = exported_only
+        @dependency_views = dependency_views
+        @layers = build_layers + extra_layers
+      end
+
+      # The absolute filesystem path serving a resource reference: a
+      # package-relative content path ("content/app.js"), or a dependency
+      # reference ("<dependency-guid>/content/app.js"). nil when no layer
+      # provides the path or it is tombstoned. Non-content paths never
+      # resolve through the view.
+      def resolve(reference)
+        return unless reference.is_a?(String)
+
+        if reference.include?("://")
+          pair = dependency_pair_for(reference)
+          return unless pair
+
+          return pair[1].resolve(reference.delete_prefix("#{pair[0]}/"))
+        end
+
+        content_relative = content_relative(reference)
+        return unless content_relative
+        return if content_relative == TOMBSTONE_FILE
+
+        result = resolve_own(content_relative)
+        return if result == :tombstoned
+        return result if result
+
+        resolve_dependencies(reference)
+      end
+
+      # The [GUID, view] pair whose GUID prefixes the reference (longest
+      # GUID first, so nested GUIDs address the innermost dependency).
+      def dependency_pair_for(reference)
+        @dependency_views
+          .sort_by { |guid, _view| -guid.length }
+          .find { |guid, _view| reference.start_with?("#{guid}/") }
+      end
+
+      private
+
+      # The serving path from the package's own layers, :tombstoned when
+      # a tombstone at or above the first hit suppresses it (tombstones
+      # also suppress the lower dependency layers), or nil when no own
+      # layer provides the path.
+      def resolve_own(content_relative)
+        tombstoned = false
+        @layers.reverse_each do |layer|
+          tombstoned ||= layer.tombstones.include?(content_relative)
+          next unless layer.file?(content_relative)
+          return :tombstoned if tombstoned
+
+          return layer.absolute(content_relative)
+        end
+        tombstoned ? :tombstoned : nil
+      end
+
+      def resolve_dependencies(relative_path)
+        @dependency_views.each do |pair|
+          found = pair.last.resolve(relative_path)
+          return found if found
+        end
+        nil
+      end
+
+      # Own layers, bottom -> top: the implicit content/ layer plus the
+      # configured storage.layers. Private layers are dropped when the view
+      # is exported-only (hidden from dependents, section 5a).
+      def build_layers
+        configs = [nil] + @storage.config.layers
+        configs = configs.reject { |config| config&.private? } if @exported_only
+        configs.filter_map { |config| build_layer(config) }
+      end
+
+      def build_layer(config)
+        root = config ? File.join(@package_path, config.path) : content_root
+        Layer.new(root: root,
+                  visibility: config&.visibility || "exported",
+                  tombstones: load_tombstones(root))
+      end
+
+      def content_root
+        File.join(@package_path, Package::CONTENT_DIR)
+      end
+
+      def load_tombstones(root)
+        tombstone_path = File.join(root, TOMBSTONE_FILE)
+        return Set.new unless File.file?(tombstone_path)
+
+        entries = JSON.parse(File.read(tombstone_path))
+        unless entries.is_a?(Array) && entries.all?(String)
+          raise Error, "Malformed #{TOMBSTONE_FILE} (expected a JSON array " \
+                       "of paths): #{tombstone_path}"
+        end
+
+        Set.new(entries)
+      rescue JSON::ParserError => e
+        raise Error, "Malformed #{TOMBSTONE_FILE}: #{tombstone_path}: #{e.message}"
+      end
+
+      def content_relative(relative_path)
+        return unless relative_path.is_a?(String)
+        return unless relative_path.start_with?(CONTENT_PREFIX)
+
+        content_relative = relative_path.delete_prefix(CONTENT_PREFIX)
+        return if @exported_only && !exported?(relative_path)
+
+        content_relative
+      end
+
+      def exported?(relative_path)
+        resource = @manifest.lookup(relative_path)
+        resource&.visibility == "exported"
+      end
+    end
+  end
+end