mxrb 0.1.0

data/lib/mxrb/official_marketplace.rb

@@ -0,0 +1,720 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'date'
+require 'fileutils'
+require 'json'
+require 'net/http'
+require 'tmpdir'
+require 'uri'
+require 'zip'
+require_relative 'official_marketplace/module_package_importer'
+require_relative 'official_marketplace/widget_package_installer'
+require_relative 'official_marketplace/lifecycle'
+require_relative 'official_marketplace/dependency_resolver'
+
+module Mxrb
+  # Installer for official/community Mendix packages, separate from Ruby modules.
+  module OfficialMarketplace
+    Package = Data.define(:name, :version, :source, :download_url, :repository)
+    OfficialPackage = Data.define(
+      :name, :version, :source, :download_url, :repository, :content_id, :version_id,
+      :content_type, :version_type, :security_issues, :private, :company_approved
+    )
+    Installation = Data.define(:package, :destination, :sha256)
+    ModuleInstallation = Data.define(
+      :package, :destination, :sha256, :module_name, :module_id, :units, :files, :archive
+    )
+
+    CATALOG = {
+      'CommunityCommons' => 'mendix/CommunityCommons',
+      'UnitTesting' => 'mendix/UnitTesting'
+    }.freeze
+
+    def self.tree_digest(path)
+      digest = Digest::SHA256.new
+      Dir.glob(File.join(path, '**', '*'), File::FNM_DOTMATCH).sort.each do |file|
+        next unless File.file?(file)
+
+        digest << file.delete_prefix("#{path}/") << "\0" << File.binread(file)
+      end
+      digest.hexdigest
+    end
+
+    def self.lock(target)
+      path = File.join(File.expand_path(target), '.mxrb', 'marketplace.lock.json')
+      File.file?(path) ? JSON.parse(File.read(path)) : { 'packages' => {} }
+    rescue JSON::ParserError => e
+      raise MarketplaceError, "invalid marketplace lockfile: #{e.message}"
+    end
+
+    def self.verify(target)
+      root = File.expand_path(target)
+      lock(root).fetch('packages').to_h do |name, entry|
+        result = case entry['kind']
+                 when 'module' then verify_module(root, name, entry)
+                 when 'widget' then verify_widget(root, entry)
+                 else verify_tree(root, entry)
+                 end
+        [name, result]
+      end
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+    def self.verify_widget(root, entry)
+      destination = File.join(root, entry.fetch('destination'))
+      archive = File.join(root, entry.fetch('archive'))
+      actual = File.file?(destination) ? Digest::SHA256.file(destination).hexdigest : nil
+      cached = File.file?(archive) ? Digest::SHA256.file(archive).hexdigest : nil
+      inventory = WidgetPackageInventory.read(destination) if actual == entry['sha256']
+      identity = inventory&.name == entry['widget_name'] && inventory&.widget_ids == entry['widget_ids']
+      {
+        valid: actual == entry['sha256'] && cached == entry['sha256'] && identity,
+        expected: entry['sha256'], actual:, cached:, identity:
+      }
+    rescue MarketplaceError
+      { valid: false, expected: entry['sha256'], actual:, cached:, identity: false }
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    def self.verify_tree(root, entry)
+      destination = File.join(root, entry.fetch('destination'))
+      actual = File.directory?(destination) ? tree_digest(destination) : nil
+      { valid: actual == entry['sha256'], expected: entry['sha256'], actual: }
+    end
+
+    def self.verify_module(root, name, entry) # rubocop:disable Metrics/AbcSize
+      archive = File.join(root, entry.fetch('archive'))
+      actual = File.file?(archive) ? Digest::SHA256.file(archive).hexdigest : nil
+      mpr_path = File.join(root, entry.fetch('destination'))
+      present = module_present?(mpr_path, name, entry['module_id'])
+      files_present = Array(entry['files']).all? { File.file?(File.join(root, _1)) }
+      {
+        valid: actual == entry['sha256'] && present && files_present,
+        expected: entry['sha256'], actual:, module_present: present, files_present:
+      }
+    end
+
+    def self.module_present?(mpr_path, name, module_id)
+      return false unless File.file?(mpr_path)
+
+      mpr = IO::MprFile.open(mpr_path, readonly: true)
+      unit = module_id ? mpr.unit(module_id) : module_by_name(mpr, name)
+      unit && mpr.parse_contents(unit)['Name'] == name
+    rescue Error, SQLite3::Exception
+      false
+    ensure
+      mpr&.close
+    end
+
+    def self.module_by_name(mpr, name)
+      mpr.units_by_containment('Modules').find { mpr.parse_contents(_1)['Name'] == name }
+    end
+
+    # Resolves a user-owned PAT file. Embedding the PAT remains an explicit,
+    # backwards-compatible opt-in for users who prefer MXRB-managed storage.
+    class Credentials
+      attr_reader :path
+
+      def initialize(path: nil, pat_file: ENV['MXRB_MENDIX_PAT_FILE'])
+        base = ENV['XDG_CONFIG_HOME'].to_s
+        base = File.join(Dir.home, '.config') if base.empty?
+        @path = path || File.join(base, 'mxrb', 'credentials')
+        @pat_file = expand_pat_file(pat_file)
+      end
+
+      def configure_pat_file(source)
+        @pat_file = expand_pat_file(source)
+        raise MarketplaceError, 'Mendix PAT file path must not be empty' unless @pat_file
+
+        read_pat_file(@pat_file)
+        write_config('mendix_pat_file' => @pat_file)
+      end
+
+      def save_pat(token)
+        value = token.to_s.strip
+        raise MarketplaceError, 'Mendix PAT must not be empty' if value.empty?
+
+        @pat_file = nil
+        write_config('mendix_pat' => value)
+      end
+
+      def pat
+        return read_pat_file(@pat_file) if @pat_file
+        return unless File.file?(@path)
+
+        config = read_config
+        source = expand_pat_file(config['mendix_pat_file'])
+        return read_pat_file(source) if source
+
+        config['mendix_pat']
+      end
+
+      private
+
+      def write_config(config)
+        FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
+        temporary = "#{@path}.tmp-#{Process.pid}"
+        File.binwrite(temporary, JSON.generate(config) << "\n")
+        File.chmod(0o600, temporary)
+        File.rename(temporary, @path)
+        @path
+      ensure
+        FileUtils.rm_f(temporary) if defined?(temporary) && temporary && File.exist?(temporary)
+      end
+
+      def read_config
+        value = JSON.parse(File.binread(@path))
+        raise MarketplaceError, 'invalid credentials file: expected a JSON object' unless value.is_a?(Hash)
+
+        value
+      rescue JSON::ParserError => e
+        raise MarketplaceError, "invalid credentials file: #{e.message}"
+      end
+
+      def expand_pat_file(value)
+        source = value.to_s.strip
+        source.empty? ? nil : File.expand_path(source)
+      end
+
+      def read_pat_file(source)
+        raise MarketplaceError, "Mendix PAT file not found: #{source}" unless File.file?(source)
+
+        raw = File.binread(source).strip
+        value = pat_from_file_contents(raw, source)
+        raise MarketplaceError, "Mendix PAT file is empty: #{source}" if value.empty?
+
+        value
+      rescue SystemCallError => e
+        raise MarketplaceError, "cannot read Mendix PAT file #{source}: #{e.message}"
+      end
+
+      def pat_from_file_contents(raw, source)
+        return pat_from_env(raw, source) if env_file?(source) || raw.match?(/^\s*(?:export\s+)?MXRB_MENDIX_PAT\s*=/)
+
+        value = JSON.parse(raw)
+        return value['mendix_pat'].to_s.strip if value.is_a?(Hash) && value.key?('mendix_pat')
+
+        raise MarketplaceError, 'JSON Mendix PAT file must contain "mendix_pat"'
+      rescue JSON::ParserError
+        raw
+      end
+
+      def env_file?(source)
+        File.basename(source).start_with?('.env')
+      end
+
+      def pat_from_env(raw, source)
+        line = raw.lines.reverse.find { _1.match?(/^\s*(?:export\s+)?MXRB_MENDIX_PAT\s*=/) }
+        raise MarketplaceError, "MXRB_MENDIX_PAT not found in #{source}" unless line
+
+        value = line.sub(/^\s*(?:export\s+)?MXRB_MENDIX_PAT\s*=\s*/, '').strip
+        value = value[1...-1] if value.length >= 2 && %w[' "].include?(value[0]) && value[-1] == value[0]
+        value.strip
+      end
+    end
+
+    # Small HTTPS-only GitHub client with bounded redirects and response size.
+    class HttpClient
+      MAX_BYTES = 512 * 1024 * 1024
+
+      def initialize(github_token: ENV['GITHUB_TOKEN'])
+        @github_token = github_token.to_s
+      end
+
+      def json(url, authorization: default_authorization)
+        JSON.parse(get(url, accept: 'application/json', authorization:))
+      rescue JSON::ParserError => e
+        raise MarketplaceError, "invalid JSON response: #{e.message}"
+      end
+
+      def download(url, destination, authorization: default_authorization)
+        File.binwrite(destination, get(url, accept: 'application/octet-stream', authorization:))
+        destination
+      end
+
+      private
+
+      def get(url, accept:, redirects: 5, authorization: default_authorization,
+              authorization_host: nil)
+        raise MarketplaceError, 'too many marketplace redirects' if redirects.negative?
+
+        uri = https_uri(url)
+        authorization_host ||= uri.host
+        scoped_authorization = authorization if uri.host == authorization_host
+        response = perform(uri, accept, scoped_authorization)
+        return response_body(response) unless response.is_a?(Net::HTTPRedirection)
+
+        options = { accept:, redirects: redirects - 1, authorization:, authorization_host: }
+        follow_redirect(uri, response, options)
+      rescue URI::InvalidURIError, SocketError, SystemCallError => e
+        raise MarketplaceError, "marketplace request failed: #{e.message}"
+      end
+
+      def follow_redirect(uri, response, options)
+        get(
+          redirect_url(uri, response['location']), **options
+        )
+      end
+
+      def redirect_url(origin, location)
+        target = URI.join(origin, location)
+        target.scheme = 'https' if origin.is_a?(URI::HTTPS) && target.host == origin.host && target.scheme == 'http'
+        target.to_s
+      end
+
+      def https_uri(url)
+        URI.parse(url).tap do |uri|
+          raise MarketplaceError, 'marketplace downloads require HTTPS' unless uri.is_a?(URI::HTTPS)
+        end
+      end
+
+      def perform(uri, accept, authorization = default_authorization)
+        request = Net::HTTP::Get.new(uri)
+        request['Accept'] = accept
+        request['User-Agent'] = "mxrb/#{Mxrb::VERSION}"
+        request['Authorization'] = authorization unless authorization.to_s.empty?
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true) { _1.request(request) }
+      end
+
+      def default_authorization
+        "Bearer #{@github_token}" unless @github_token.empty?
+      end
+
+      def response_body(response)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise MarketplaceError, "marketplace request failed with HTTP #{response.code}"
+        end
+        raise MarketplaceError, 'marketplace response exceeds 512 MiB' \
+          if response.body.to_s.bytesize > MAX_BYTES
+
+        response.body
+      end
+    end
+
+    require_relative 'official_marketplace/content_api'
+
+    # Resolves known names or explicit github:org/repo releases.
+    class GitHubResolver
+      def initialize(client: HttpClient.new)
+        @client = client
+      end
+
+      def search(query)
+        local = catalog_search(query)
+        return local unless local.empty?
+
+        github_search(query)
+      end
+
+      def catalog_search(query)
+        term = query.to_s.downcase
+        CATALOG.filter_map do |name, repository|
+          { name:, repository: } if name.downcase.include?(term) || repository.downcase.include?(term)
+        end
+      end
+
+      def github_search(query)
+        payload = @client.json(
+          "https://api.github.com/search/repositories?q=#{URI.encode_www_form_component(query)}+org:mendix"
+        )
+        Array(payload['items']).first(20).map do |item|
+          { name: item['name'], repository: item['full_name'], description: item['description'] }
+        end
+      end
+
+      def resolve(identifier, version: nil)
+        repository, name = repository_and_name(identifier)
+        endpoint = release_endpoint(version)
+        release = @client.json("https://api.github.com/repos/#{repository}/#{endpoint}")
+        download_url = release_download(release)
+        Package.new(name, release['tag_name'] || version || 'latest', :github, download_url, repository)
+      rescue KeyError => e
+        raise MarketplaceError, "GitHub release is incomplete: #{e.message}"
+      end
+
+      private
+
+      def release_endpoint(version)
+        version ? "releases/tags/#{URI.encode_www_form_component(version)}" : 'releases/latest'
+      end
+
+      def release_download(release)
+        assets = Array(release['assets'])
+        asset = %w[.mpk .zip].filter_map do |extension|
+          assets.find { _1['name'].to_s.downcase.end_with?(extension) }
+        end.first
+        asset ? asset.fetch('browser_download_url') : release.fetch('zipball_url')
+      end
+
+      def repository_and_name(identifier)
+        source = identifier.to_s.delete_prefix('github:')
+        repository = source.include?('/') ? source : CATALOG[source]
+        raise MarketplaceError, "no GitHub repository is known for #{identifier.inspect}" unless repository
+
+        [repository, source.split('/').last]
+      end
+    end
+
+    # Safely extracts GitHub or local MPK archives into the target project.
+    class Installer # rubocop:disable Metrics/ClassLength
+      ATLAS_VARIABLES_IMPORT = '@import "../../themesource/atlas_core/web/variables";'
+      IMPORTABLE_CONTENT_TYPES = %w[Module Service].freeze
+      DOWNLOADABLE_CONTENT_TYPES = (IMPORTABLE_CONTENT_TYPES + %w[Widget]).freeze
+
+      def initialize(target:, client: HttpClient.new, mpr: nil)
+        @target = File.expand_path(target)
+        @client = client
+        @mpr = mpr && File.expand_path(mpr)
+      end
+
+      def pull(identifier, version: nil, mpr: @mpr)
+        package = GitHubResolver.new(client: @client).resolve(identifier, version:)
+        Dir.mktmpdir('mxrb-marketplace-') do |dir|
+          archive = @client.download(package.download_url, File.join(dir, 'package.zip'))
+          mpr ? import_module(archive, package, mpr) : install_archive(archive, package)
+        end
+      end
+
+      def pull_official(identifier, version: nil, mendix_version: nil,
+                        allow_vulnerable: false, api: ContentApi.new)
+        mpr = @mpr
+        raise MarketplaceError, 'official Marketplace module pull requires --mpr FILE.mpr' unless mpr
+
+        mendix_version ||= detect_mendix_version(mpr)
+        package = api.resolve(identifier, version:, mendix_version:, allow_vulnerable:)
+        validate_official_package!(package)
+        download_official(package, mpr, api)
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
+      def update_official(identifier, version: nil, mendix_version: nil,
+                          allow_vulnerable: false, apply: false, api: ContentApi.new)
+        lifecycle = Lifecycle.new(target: @target, mpr: @mpr, installer: self)
+        _name, installed = lifecycle.installed(identifier)
+        content_id = installed['content_id'] || identifier
+        mpr = lifecycle.mpr_path(installed)
+        mendix_version ||= detect_mendix_version(mpr)
+        package = api.resolve(content_id, version:, mendix_version:, allow_vulnerable:)
+        validate_official_package!(package)
+        Dir.mktmpdir('mxrb-marketplace-update-') do |dir|
+          archive = api.download(
+            package.version_id, File.join(dir, 'package.mpk'), download_url: package.download_url
+          )
+          plan = lifecycle.plan_update(identifier, archive, package)
+          plan.apply! if apply
+          plan
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
+
+      def remove(identifier, apply: false)
+        plan = Lifecycle.new(target: @target, mpr: @mpr, installer: self).plan_remove(identifier)
+        plan.apply! if apply
+        plan
+      end
+
+      def dependencies(identifier, apply: false, apply_resolved: false, api: ContentApi.new)
+        lifecycle = Lifecycle.new(target: @target, mpr: @mpr, installer: self)
+        _name, entry = lifecycle.installed(identifier)
+        mpr = lifecycle.mpr_path(entry)
+        resolver = DependencyResolver.new(
+          target: @target, mpr:, installer: self, api:,
+          mendix_version: detect_mendix_version(mpr)
+        )
+        resolver.resolve(identifier, apply:, apply_resolved:)
+      end
+
+      def download_official(package, mpr, api)
+        Dir.mktmpdir('mxrb-marketplace-') do |dir|
+          archive = api.download(
+            package.version_id, File.join(dir, 'package.mpk'), download_url: package.download_url
+          )
+          install_official_archive(archive, package, mpr)
+        end
+      end
+
+      def validate_official_package!(package)
+        return if DOWNLOADABLE_CONTENT_TYPES.include?(package.content_type)
+
+        raise MarketplaceError,
+              "Marketplace content #{package.name.inspect} is #{package.content_type}, not a Module, Service, or Widget"
+      end
+
+      def import(path, name: nil, mpr: @mpr)
+        source = File.expand_path(path)
+        raise MarketplaceError, "package not found: #{source}" unless File.file?(source)
+
+        package_name = valid_name(name || File.basename(source, File.extname(source)))
+        package = Package.new(package_name, 'local', :mpk, source, nil)
+        mpr ? import_module(source, package, mpr) : install_archive(source, package)
+      end
+
+      private
+
+      def install_official_archive(archive, package, mpr) # rubocop:disable Metrics/MethodLength
+        case PackageEnvelope.kind(archive)
+        when :module
+          import_module(archive, package, mpr)
+        when :widget
+          unless package.content_type == 'Widget'
+            raise MarketplaceError,
+                  "Marketplace #{package.content_type} archive declares a clientModule widget"
+          end
+          WidgetPackageInstaller.new(target: @target).install(archive, package)
+        else
+          raise MarketplaceError, 'unsupported official Marketplace package envelope'
+        end
+      end
+
+      def detect_mendix_version(mpr)
+        file = IO::MprFile.open(mpr, readonly: true)
+        file.mendix_version
+      ensure
+        file&.close
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def import_module(archive, package, mpr)
+        relative_target_path(mpr)
+        inventory = ModulePackageInventory.read(archive)
+        originals, created_backups = preserve_asset_originals(inventory)
+        result = module_importer(
+          archive, mpr, package, protected_files: protected_package_assets(inventory.name)
+        ).import!
+        ensure_atlas_theme_variables
+        resolved = resolved_package(package, result)
+        sha256 = Digest::SHA256.file(archive).hexdigest
+        cached = cache_package(archive, resolved, sha256)
+        write_module_lock(resolved, mpr, result, cached, sha256, originals)
+        ModuleInstallation.new(
+          resolved, File.expand_path(mpr), sha256, result.module_name, result.module_id,
+          result.units, result.files, cached
+        )
+      rescue StandardError
+        Array(created_backups).each { FileUtils.rm_f(_1) }
+        raise
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      def module_importer(archive, mpr, package, protected_files: [])
+        ModulePackageImporter.new(
+          archive, mpr, target_root: @target, allow_model_upgrade: package.source == :mendix,
+                        protected_files:
+        )
+      end
+
+      def protected_package_assets(package_name)
+        OfficialMarketplace.lock(@target).fetch('packages').flat_map do |name, entry|
+          next [] if name == package_name
+
+          Array(entry['files'])
+        end.uniq
+      end
+
+      def ensure_atlas_theme_variables
+        atlas = File.join(@target, 'themesource', 'atlas_core', 'web', '_variables.scss')
+        return unless File.file?(atlas)
+
+        custom = File.join(@target, 'theme', 'web', 'custom-variables.scss')
+        content = File.file?(custom) ? File.read(custom) : ''
+        return if content.include?(ATLAS_VARIABLES_IMPORT)
+
+        FileUtils.mkdir_p(File.dirname(custom))
+        File.write(custom, [content.rstrip, ATLAS_VARIABLES_IMPORT, ''].reject(&:empty?).join("\n\n"))
+      end
+
+      def resolved_package(package, result)
+        manifest_version = result.package_version.to_s
+        version = manifest_version.empty? || manifest_version == 'unknown' ? package.version : manifest_version
+        values = { name: result.module_name, version: }
+        return package.with(**values) if package.respond_to?(:content_id)
+
+        Package.new(
+          values.fetch(:name), values.fetch(:version), package.source,
+          package.download_url, package.repository
+        )
+      end
+
+      def cache_package(archive, package, sha256)
+        version = package.version.to_s.gsub(/[^A-Za-z0-9_.-]/, '_')
+        destination = File.join(@target, '.mxrb', 'marketplace', "#{package.name}-#{version}.mpk")
+        FileUtils.mkdir_p(File.dirname(destination))
+        FileUtils.cp(archive, destination) unless File.expand_path(archive) == destination
+        raise MarketplaceError, 'cached marketplace package checksum mismatch' unless
+          Digest::SHA256.file(destination).hexdigest == sha256
+
+        destination
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
+      def write_module_lock(package, mpr, result, cached, digest, originals)
+        path = File.join(@target, '.mxrb', 'marketplace.lock.json')
+        FileUtils.mkdir_p(File.dirname(path))
+        lock = OfficialMarketplace.lock(@target)
+        lock['packages'][package.name] = {
+          'kind' => 'module', 'version' => package.version, 'source' => package.source,
+          'repository' => package.repository, 'sha256' => digest,
+          'destination' => relative_target_path(mpr), 'archive' => relative_target_path(cached),
+          'module_id' => result.module_id, 'units' => result.units, 'files' => result.files,
+          'asset_originals' => originals
+        }.merge(official_lock_metadata(package)).compact
+        write_lock_atomically(path, lock)
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def preserve_asset_originals(inventory)
+        existing = OfficialMarketplace.lock(@target).dig('packages', inventory.name)
+        legacy = Array(existing&.fetch('files', [])).to_h { [_1, nil] }
+        retained = existing&.fetch('asset_originals', legacy) || {}
+        originals = inventory.files.keys.to_h do |relative|
+          [relative, retained.key?(relative) ? retained[relative] : preserve_asset(relative, inventory.name)]
+        end
+        created = originals.values.compact.filter_map do |relative|
+          path = safe_target_path(relative)
+          path unless retained.value?(relative)
+        end
+        [originals, created]
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      def preserve_asset(relative, module_name)
+        source = safe_target_path(relative)
+        raise MarketplaceError, "package asset destination is a symbolic link: #{relative}" if File.symlink?(source)
+        return unless File.file?(source)
+
+        backup = safe_target_path(File.join('.mxrb', 'marketplace-originals', valid_name(module_name), relative))
+        FileUtils.mkdir_p(File.dirname(backup))
+        FileUtils.cp(source, backup)
+        relative_target_path(backup)
+      end
+
+      def safe_target_path(relative)
+        path = File.expand_path(File.join(@target, relative.to_s))
+        prefix = "#{@target}#{File::SEPARATOR}"
+        raise MarketplaceError, "path is outside marketplace target: #{path}" unless path.start_with?(prefix)
+
+        path
+      end
+
+      def official_lock_metadata(package)
+        return {} unless package.respond_to?(:content_id)
+
+        {
+          'content_id' => package.content_id, 'version_id' => package.version_id,
+          'content_type' => package.content_type, 'version_type' => package.version_type,
+          'security_issues' => package.security_issues, 'private' => package.private,
+          'company_approved' => package.company_approved
+        }
+      end
+
+      def relative_target_path(path)
+        absolute = File.expand_path(path)
+        prefix = "#{@target}#{File::SEPARATOR}"
+        raise MarketplaceError, "path is outside marketplace target: #{absolute}" unless absolute.start_with?(prefix)
+
+        absolute.delete_prefix(prefix)
+      end
+
+      # Transaction boundary intentionally keeps rollback and cleanup together.
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def install_archive(archive, package)
+        name = valid_name(package.name)
+        destination = File.join(@target, 'modules', name)
+        raise MarketplaceError, "module destination already exists: #{destination}" if File.exist?(destination)
+
+        staging = File.join(@target, '.mxrb', 'marketplace-staging', "#{name}-#{Process.pid}")
+        extract_zip(archive, staging)
+        move_into_project(staging, destination)
+        digest = OfficialMarketplace.tree_digest(destination)
+        write_lock(package, destination, digest)
+        Installation.new(package, destination, digest)
+      rescue StandardError
+        FileUtils.rm_rf(destination) if defined?(destination) && destination && File.exist?(destination)
+        raise
+      ensure
+        FileUtils.rm_rf(staging) if defined?(staging) && staging && File.exist?(staging)
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      def extract_zip(archive, staging)
+        FileUtils.mkdir_p(staging)
+        Zip::File.open(archive) do |zip|
+          zip.each { extract_safe_entry(_1, staging) }
+        end
+      rescue Zip::Error => e
+        raise MarketplaceError, "invalid MPK/ZIP package: #{e.message}"
+      end
+
+      def extract_safe_entry(entry, staging)
+        destination = safe_destination(entry.name, staging)
+
+        entry.directory? ? FileUtils.mkdir_p(destination) : extract_entry(entry, destination)
+      end
+
+      def safe_destination(name, staging)
+        relative = name.to_s
+        unsafe = relative.start_with?('/', '\\') || relative.split(%r{[\\/]}).include?('..')
+        raise MarketplaceError, "unsafe package path #{name.inspect}" if unsafe
+
+        destination = File.expand_path(File.join(staging, relative))
+        prefix = "#{File.expand_path(staging)}#{File::SEPARATOR}"
+        raise MarketplaceError, "unsafe package path #{name.inspect}" unless destination.start_with?(prefix)
+
+        destination
+      end
+
+      def extract_entry(entry, destination)
+        FileUtils.mkdir_p(File.dirname(destination))
+        File.open(destination, 'wb') { ::IO.copy_stream(entry.get_input_stream, _1) }
+      end
+
+      def collapse_single_root(staging)
+        children = Dir.children(staging)
+        if children.one? && File.directory?(File.join(staging, children.first))
+          return File.join(staging, children.first)
+        end
+
+        staging
+      end
+
+      def move_into_project(staging, destination)
+        FileUtils.mkdir_p(File.dirname(destination))
+        FileUtils.mv(collapse_single_root(staging), destination)
+      end
+
+      def valid_name(value)
+        name = value.to_s.gsub(/[^A-Za-z0-9_]/, '')
+        raise MarketplaceError, "invalid marketplace module name #{value.inspect}" \
+          unless name.match?(/\A[A-Za-z][A-Za-z0-9_]*\z/)
+
+        name
+      end
+
+      def write_lock(package, destination, digest)
+        path = File.join(@target, '.mxrb', 'marketplace.lock.json')
+        FileUtils.mkdir_p(File.dirname(path))
+        lock = OfficialMarketplace.lock(@target)
+        lock['packages'][package.name] = lock_entry(package, destination, digest)
+        write_lock_atomically(path, lock)
+      end
+
+      def lock_entry(package, destination, digest)
+        {
+          'version' => package.version, 'source' => package.source,
+          'repository' => package.repository, 'sha256' => digest,
+          'destination' => destination.delete_prefix("#{@target}/")
+        }.merge(official_lock_metadata(package)).compact
+      end
+
+      def write_lock_atomically(path, lock)
+        temporary = "#{path}.tmp-#{Process.pid}"
+        File.write(temporary, JSON.pretty_generate(lock) << "\n")
+        File.rename(temporary, path)
+      ensure
+        FileUtils.rm_f(temporary) if defined?(temporary) && temporary && File.exist?(temporary)
+      end
+    end
+  end
+end