ocran 1.4.6 → 1.5.0

data/lib/ocran/ed_resource.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+require "fiddle/import"
+require "fiddle/types"
+# The language/codepage constants and the pure-Ruby blob builder live in a
+# separate, dlload-free file so they can be unit-tested on any platform.
+require_relative "ed_resource_builder"
+
+module Ocran
+  # Edits PE resources in an executable, in the style of rcedit:
+  #   * RT_VERSION  - version info (VS_VERSIONINFO / VS_FIXEDFILEINFO / StringFileInfo)
+  #   * RT_MANIFEST - application manifest / requested execution level
+  #   * RT_STRING   - string table entries by numeric ID
+  #
+  # This is a sibling of EdIcon and uses the same Windows resource-update API
+  # (BeginUpdateResourceW / UpdateResourceW / EndUpdateResourceW) via Fiddle.
+  module EdResource
+    extend Fiddle::Importer
+    dlload "kernel32.dll"
+
+    include Fiddle::Win32Types
+    typealias "LPVOID", "void*"
+    typealias "LPCWSTR", "char*"
+
+    MAKEINTRESOURCE = -> (i) { Fiddle::Pointer.new(i) }
+    RT_VERSION = MAKEINTRESOURCE.(16)
+    RT_STRING = MAKEINTRESOURCE.(6)
+    # CREATEPROCESS_MANIFEST_RESOURCE_ID == 1; the manifest is stored under
+    # resource type RT_MANIFEST (24), name id 1.
+    RT_MANIFEST = MAKEINTRESOURCE.(24)
+    MANIFEST_RESOURCE_ID = 1
+
+    # Language/codepage constants (MAKELANGID, LANGID, LANGID_US_ENGLISH,
+    # CODEPAGE_UNICODE, STRING_TABLE_KEY), EXECUTION_LEVELS and
+    # MANIFEST_TEMPLATE are defined in ed_resource_builder.rb, required above.
+
+    extern "DWORD GetLastError()"
+    extern "HANDLE BeginUpdateResourceW(LPCWSTR, BOOL)"
+    extern "BOOL EndUpdateResourceW(HANDLE, BOOL)"
+    extern "BOOL UpdateResourceW(HANDLE, LPCWSTR, LPCWSTR, WORD, LPVOID, DWORD)"
+
+    class << self
+      # Perform every requested resource edit under a single
+      # BeginUpdateResource/EndUpdateResource cycle (one PE rewrite).
+      def update(executable_filename, version_strings: nil, file_version: nil,
+                 product_version: nil, resource_strings: nil, manifest_xml: nil,
+                 execution_level: nil)
+        wants_version = !blank?(version_strings) || file_version || product_version
+        wants_manifest = manifest_xml || execution_level
+        wants_strings = !blank?(resource_strings)
+        return unless wants_version || wants_manifest || wants_strings
+
+        update_resource(executable_filename) do |handle|
+          write_version_info(handle, version_strings || {}, file_version, product_version) if wants_version
+          write_manifest(handle, manifest_xml, execution_level) if wants_manifest
+          write_resource_strings(handle, resource_strings) if wants_strings
+        end
+      end
+
+      private
+
+      def blank?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+
+      def write_version_info(handle, strings, file_version, product_version)
+        merged = {}
+        strings.each { |k, v| merged[k.to_s] = v }
+        merged["FileVersion"] = file_version if file_version
+        merged["ProductVersion"] = product_version if product_version
+
+        blob = Build.version_info(
+          strings: merged,
+          file_version: file_version || merged["FileVersion"] || "0.0.0.0",
+          product_version: product_version || merged["ProductVersion"] || "0.0.0.0"
+        )
+        put(handle, RT_VERSION, 1, blob)
+      end
+
+      def write_manifest(handle, manifest_xml, execution_level)
+        xml = Build.manifest(manifest_xml, execution_level)
+        put(handle, RT_MANIFEST, MANIFEST_RESOURCE_ID, xml.b)
+      end
+
+      def write_resource_strings(handle, id_to_value)
+        id_to_value.group_by { |id, _| id.to_i / 16 }.each do |bundle_index, pairs|
+          bundle = Build.string_bundle(pairs.to_h)
+          put(handle, RT_STRING, bundle_index + 1, bundle)
+        end
+      end
+
+      def put(handle, type, name, data)
+        name_arg = name.is_a?(Integer) ? MAKEINTRESOURCE.(name) : name
+        if UpdateResourceW(handle, type, name_arg, LANGID, data, data.bytesize) == 0
+          raise "Failed to UpdateResourceW(#{GetLastError()})"
+        end
+      end
+
+      def update_resource(executable_filename)
+        path = File.expand_path(executable_filename).encode("UTF-16LE").b + "\x00\x00".b
+        handle = BeginUpdateResourceW(path, 0)
+        if handle == Fiddle::NULL
+          raise "Failed to BeginUpdateResourceW(#{GetLastError()})"
+        end
+
+        yield(handle)
+
+        if EndUpdateResourceW(handle, 0) == 0
+          raise "Failed to EndUpdateResourceW(#{GetLastError()})"
+        end
+      end
+    end
+  end
+end

data/lib/ocran/ed_resource_builder.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Ocran
+  # Language/codepage identifiers and the pure-Ruby builder for the binary
+  # PE-resource blobs (VS_VERSIONINFO and RT_STRING bundles).
+  #
+  # This file is deliberately free of any Windows API / dlload dependency, so
+  # the fiddly resource-blob construction can be required and unit-tested on
+  # any platform. The Windows-only injection of these blobs
+  # (BeginUpdateResource / UpdateResourceW / EndUpdateResource) lives in
+  # ed_resource.rb, which requires this file.
+  module EdResource
+    MAKELANGID = -> (p, s) { s << 10 | p }
+    LANG_ENGLISH = 0x09
+    SUBLANG_ENGLISH_US = 0x01
+
+    # US English / Unicode. Resources are written under this language id so the
+    # manifest write replaces (rather than duplicates) the stub's compiled-in
+    # RT_MANIFEST, which windres stores under 0x0409. The same id is used for the
+    # StringTable key ("040904B0") and the VarFileInfo Translation value (langid
+    # in the low word, codepage in the high word).
+    LANGID_US_ENGLISH = MAKELANGID.(LANG_ENGLISH, SUBLANG_ENGLISH_US) # 0x0409
+    LANGID = LANGID_US_ENGLISH
+    CODEPAGE_UNICODE = 0x04B0
+    STRING_TABLE_KEY = format("%04X%04X", LANGID_US_ENGLISH, CODEPAGE_UNICODE)
+
+    EXECUTION_LEVELS = %w[asInvoker highestAvailable requireAdministrator].freeze
+
+    # Baseline manifest, copied verbatim from src/stub.manifest. Inlined as a
+    # constant so the installed gem has no runtime dependency on the src tree.
+    MANIFEST_TEMPLATE = <<~MANIFEST
+      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+      <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
+        <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
+          <security>
+            <requestedPrivileges>
+              <requestedExecutionLevel level="asInvoker"/>
+            </requestedPrivileges>
+          </security>
+        </trustInfo>
+        <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
+          <application>
+            <!--The ID below indicates application support for Windows Vista -->
+            <supportedOS Id="{e2011457-1546-43c5-a5fe-008deee3d3f0}"/>
+            <!--The ID below indicates application support for Windows 7 -->
+            <supportedOS Id="{35138b9a-5d96-4fbd-8e2d-a2440225f93a}"/>
+            <!--The ID below indicates application support for Windows 8 -->
+            <supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}"/>
+            <!--The ID below indicates application support for Windows 8.1 -->
+            <supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}"/>
+            <!--The ID below indicates application support for Windows 10 -->
+            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
+          </application>
+        </compatibility>
+        <application>
+          <windowsSettings>
+            <activeCodePage xmlns="http://schemas.microsoft.com/SMI/2019/WindowsSettings">UTF-8</activeCodePage>
+          </windowsSettings>
+        </application>
+      </assembly>
+    MANIFEST
+
+    # Builds the binary blobs (VS_VERSIONINFO, RT_STRING bundles) and the
+    # manifest XML that Windows expects. All structures are little-endian.
+    # Shared with the --static-runtime resource writer (pe_resources.rb), which
+    # runs on any build host; ed_resource.rb needs Windows.
+    module Build
+      module_function
+
+      # The level attribute of a requestedExecutionLevel element, wherever it
+      # sits among the element's attributes, or an XML comment or CDATA section
+      # (so element-shaped text inside one is skipped).
+      REQUESTED_EXECUTION_LEVEL = /<!--.*?-->|<!\[CDATA\[.*?\]\]>|(<(?:[\w.-]+:)?requestedExecutionLevel\b[^>]*?\slevel\s*=\s*)(["'])[^"']*\2/m
+
+      # The RT_MANIFEST XML: the given manifest (or the stub's baseline one)
+      # with its requestedExecutionLevel replaced when execution_level is given.
+      def manifest(manifest_xml, execution_level)
+        xml = manifest_xml || MANIFEST_TEMPLATE
+        return xml unless execution_level
+
+        unless EXECUTION_LEVELS.include?(execution_level)
+          raise "Invalid requested execution level: #{execution_level}"
+        end
+        patched = false
+        xml.gsub(REQUESTED_EXECUTION_LEVEL) do
+          next $& if patched || !$1
+
+          patched = true
+          "#{$1}#{$2}#{execution_level}#{$2}"
+        end
+      end
+
+      NUL16 = [0].pack("v").freeze
+
+      # UTF-16LE, NUL-terminated, as a binary string.
+      def wsz(str)
+        str.to_s.encode("UTF-16LE").b + NUL16
+      end
+
+      NODE_HEADER_SIZE = 6 # wLength + wValueLength + wType, three WORDs
+
+      # A generic VS_VERSIONINFO node: a 6-byte header (wLength, wValueLength,
+      # wType) followed by a NUL-terminated UTF-16LE key, DWORD-aligned Value,
+      # then DWORD-aligned children.
+      #
+      # Padding aligns Value and each child to a 32-bit boundary relative to the
+      # start of the node, so the NODE_HEADER_SIZE prefix is included when
+      # computing pad lengths. (Each node itself starts on a 4-byte boundary
+      # because parents pad before appending children, and the whole blob is
+      # placed at an aligned resource offset.)
+      #
+      # value_len is stored verbatim in wValueLength: callers pass bytes for
+      # binary values and WORD counts for string values (the Win32 quirk).
+      def node(key:, wtype:, value: nil, value_len: 0, children: [])
+        body = +"".b
+        pad = -> { body << ("\x00".b * ((-(NODE_HEADER_SIZE + body.bytesize)) & 3)) }
+
+        body << wsz(key)
+        pad.call
+        body << value if value
+        unless children.empty?
+          pad.call
+          children.each do |c|
+            pad.call
+            body << c
+          end
+        end
+        wlength = NODE_HEADER_SIZE + body.bytesize
+        [wlength, value_len, wtype].pack("vvv") + body
+      end
+
+      # Split "X.Y.Z.W" into four integers, padding/truncating to 4.
+      def quad(ver)
+        parts = ver.to_s.split(".").map(&:to_i)
+        parts.fill(0, parts.size...4)[0, 4]
+      end
+
+      # VS_FIXEDFILEINFO (52 bytes).
+      def fixed_file_info(file_ver, prod_ver)
+        fa, fb, fc, fd = quad(file_ver)
+        pa, pb, pc, pd = quad(prod_ver)
+        [
+          0xFEEF04BD,         # dwSignature
+          0x00010000,         # dwStrucVersion (1.0)
+          (fa << 16) | fb,    # dwFileVersionMS
+          (fc << 16) | fd,    # dwFileVersionLS
+          (pa << 16) | pb,    # dwProductVersionMS
+          (pc << 16) | pd,    # dwProductVersionLS
+          0x0000003F,         # dwFileFlagsMask
+          0x00000000,         # dwFileFlags
+          0x00000004,         # dwFileOS = VOS__WINDOWS32
+          0x00000001,         # dwFileType = VFT_APP
+          0x00000000,         # dwFileSubtype
+          0x00000000,         # dwFileDateMS
+          0x00000000          # dwFileDateLS
+        ].pack("V13")
+      end
+
+      # One String node. wValueLength is in UTF-16 code units (WORDs),
+      # including the NUL terminator.
+      def string_node(key, value)
+        v = wsz(value)
+        node(key: key, wtype: 1, value: v, value_len: v.bytesize / 2)
+      end
+
+      # Build the full VS_VERSIONINFO blob for RT_VERSION.
+      def version_info(strings:, file_version:, product_version:)
+        str_children = strings.map { |k, v| string_node(k.to_s, v) }
+        string_table = node(key: STRING_TABLE_KEY, wtype: 1, children: str_children)
+        string_file_info = node(key: "StringFileInfo", wtype: 1, children: [string_table])
+
+        translation = node(
+          key: "Translation", wtype: 0,
+          value: [(CODEPAGE_UNICODE << 16) | LANGID_US_ENGLISH].pack("V"),
+          value_len: 4
+        )
+        var_file_info = node(key: "VarFileInfo", wtype: 1, children: [translation])
+
+        ffi = fixed_file_info(file_version, product_version)
+        node(
+          key: "VS_VERSION_INFO", wtype: 0, value: ffi, value_len: ffi.bytesize,
+          children: [string_file_info, var_file_info]
+        )
+      end
+
+      # Build one RT_STRING bundle (16 slots). id_to_value contains only IDs
+      # belonging to this bundle. Each entry is a WORD length (in WORDs, no NUL
+      # terminator) followed by the UTF-16LE characters; empty slots are 0x0000.
+      def string_bundle(id_to_value)
+        slots = Array.new(16) { NUL16.dup }
+        id_to_value.each do |id, value|
+          u = value.to_s.encode("UTF-16LE").b
+          slots[id.to_i % 16] = [u.bytesize / 2].pack("v") + u
+        end
+        slots.join.b
+      end
+    end
+  end
+end

data/lib/ocran/file_path_set.rb

@@ -45,21 +45,25 @@ module Ocran
         raise ArgumentError, "Relative paths such as '.' or '..' are not allowed, given: #{target}"
       end
 
-      if (path = @set[target])
-        if path.eql?(source)
+      # Keyed on the normalized target: Hash does not see the refined
+      # Pathname#eql?/hash, and on Windows "lib/Foo.rb" and "lib\foo.rb" are
+      # one file that must not be written twice.
+      key = target.path_key
+      if (entry = @set[key])
+        if entry[1].eql?(source)
           return nil
         else
-          raise "Conflicting sources for the same target. Target: #{target}, Existing Source: #{path}, Given Source: #{source}"
+          raise "Conflicting sources for the same target. Target: #{target}, Existing Source: #{entry[1]}, Given Source: #{source}"
         end
       end
 
-      @set[target] = source
+      @set[key] = [target, source]
       self
     end
 
     def each
       return to_enum(__method__) unless block_given?
-      @set.each { |target, source| yield(source, target) }
+      @set.each_value { |target, source| yield(source, target) }
     end
 
     def to_a

data/lib/ocran/gem_spec_queryable.rb

@@ -155,7 +155,10 @@ module Ocran
       actual_files = file_sets.flat_map do |set|
         case set
         when :spec
-          files.map { |file| Pathname(file) }
+          # Gem::Specification#files lists paths relative to the gem
+          # directory, and may name files the installed gem does not have
+          # (e.g. excluded from the package).
+          files.map { |file| gem_root / file }.select(&:file?)
         when :loaded
           # Some distros expose gem files under additional paths via symlinks
           # (e.g. Fedora symlinks /usr/share/ruby/psych.rb into the psych gem
@@ -186,8 +189,9 @@ module Ocran
           raise "Invalid file set: #{set}. Please specify a valid file set (:spec, :loaded, :files, :extras, :scripts)."
         end
       end
-      actual_files.uniq
-      actual_files
+      # The file sets overlap (e.g. :loaded and :scripts). Keyed on path_key
+      # because Array#uniq does not see the refined Pathname#eql?.
+      actual_files.uniq { |file| file.path_key }
     end
   end
 end

data/lib/ocran/host_config_helper.rb

@@ -22,13 +22,23 @@ module Ocran
       @libdir ||= Pathname.new(RbConfig::CONFIG["libdir"])
     end
 
+    # True when the interpreter links against a shared libruby that has to
+    # be packed next to it. A Ruby configured without --enable-shared still
+    # reports LIBRUBY_SO (e.g. "libruby.so.4.0.6") although only
+    # libruby-static.a is installed and the interpreter is self-contained.
+    def shared_libruby?
+      RbConfig::CONFIG["ENABLE_SHARED"] != "no"
+    end
+
     def libruby_so
+      return nil unless shared_libruby?
       name = RbConfig::CONFIG["LIBRUBY_SO"]
       return nil if name.nil? || name.empty?
-      @libruby_so ||= Pathname.new(name)
+      Pathname.new(name)
     end
 
     def libruby_aliases
+      return [] unless shared_libruby?
       aliases = RbConfig::CONFIG["LIBRUBY_ALIASES"]
       return [] if aliases.nil? || aliases.empty?
       aliases.split.map { |name| Pathname.new(name) }

data/lib/ocran/inno_setup_script_builder.rb

@@ -10,18 +10,18 @@ module Ocran
     ISCC_INVALID_PARAMS = 1
     ISCC_COMPILATION_FAILED = 2
 
-    extend WindowsCommandEscaping
-
     class << self
+      # Whether the ISCC command can be run. On Windows it is invoked
+      # directly and a missing ISCC is reported by compile; on POSIX it is
+      # looked up in PATH (e.g. a Wine wrapper, or a fake ISCC in tests).
+      def iscc_available?
+        return true if Gem.win_platform?
+
+        system("command -v #{ISCC_CMD} > /dev/null 2>&1")
+      end
+
       def compile(iss_filename, quiet: false)
-        # "where" and ">NUL" only exist on Windows; use "command -v" on POSIX
-        # (e.g. when testing the pipeline with a fake ISCC on Linux/macOS).
-        iscc_found = if Gem.win_platform?
-                       true # ISCC is invoked directly; failure is reported below
-                     else
-                       system("command -v #{quote_and_escape(ISCC_CMD)} > /dev/null 2>&1")
-                     end
-        unless iscc_found
+        unless iscc_available?
           raise "ISCC command not found. Is the InnoSetup directory in your PATH?"
         end
 
@@ -101,22 +101,32 @@ module Ocran
       @files.add?(source, target)
     end
 
+    # Inno Setup expands "{...}" as a constant (e.g. {app}) in the Name,
+    # DestDir and DestName parameters, and "{{" is how a literal brace is
+    # written there. Source is read by the compiler, which expands no
+    # constants in it (short of the external flag), so it stays as it is.
+    def escape_braces(s)
+      s.to_s.gsub("{", "{{")
+    end
+    private :escape_braces
+
     def build_dir_item(target)
-      name = File.join("{app}", target)
+      name = File.join("{app}", escape_braces(target))
       "Name: #{quote_and_escape(name)};"
     end
     private :build_dir_item
 
     def build_file_item(source, target)
-      dest_dir = File.join("{app}", File.dirname(target))
+      dest_dir = File.join("{app}", escape_braces(File.dirname(target)))
       s = [
         "Source: #{quote_and_escape(source)};",
         "DestDir: #{quote_and_escape(dest_dir)};"
       ]
       src_name = File.basename(source)
       dest_name = File.basename(target)
-      if src_name != dest_name
-        s << "DestName: #{quote_and_escape(dest_name)};"
+      # A name taken over from Source would be expanded unescaped.
+      if src_name != dest_name || dest_name.include?("{")
+        s << "DestName: #{quote_and_escape(escape_braces(dest_name))};"
       end
       s.join(" ")
     end

data/lib/ocran/launcher_batch_builder.rb

@@ -27,7 +27,7 @@ module Ocran
     def build
       @build_file.tap do |f|
         f.puts "@echo off"
-        @environments.each { |name, val| f.puts build_set_command(name, val) }
+        @environments.each { |name, val| f.puts build_set_command(name, batch_value(val, BATCH_FILE_DIR)) }
         f.puts build_set_command("OCRAN_EXECUTABLE", BATCH_FILE_PATH)
         f.puts build_start_command(@title, @executable, @script, *@args, chdir_before: @chdir_before)
         f
@@ -47,13 +47,10 @@ module Ocran
       @executable, @script, @args = executable, script, args
     end
 
-    def replace_inst_dir_placeholder(s)
-      s.to_s.gsub(/#{Regexp.escape(EXTRACT_ROOT.to_s)}[\/\\]/, BATCH_FILE_DIR)
-    end
-    private :replace_inst_dir_placeholder
-
+    # +value+ is inserted as is and must already be escaped (see
+    # WindowsCommandEscaping#batch_value).
     def build_set_command(name, value)
-      "set \"#{name}=#{replace_inst_dir_placeholder(value)}\""
+      "set \"#{name}=#{value}\""
     end
     private :build_set_command
 
@@ -61,7 +58,7 @@ module Ocran
       cmd = ["start"]
 
       # Title for Command Prompt window title bar
-      cmd << quote_and_escape(title)
+      cmd << quote_and_escape(escape_percent(title))
 
       # Use /d to set the startup directory for the process,
       # which will be BATCH_FILE_DIR/SRCDIR. This path is where
@@ -71,9 +68,9 @@ module Ocran
         cmd << "/d #{quote_and_escape("#{BATCH_FILE_DIR}#{SRCDIR}")}"
       end
 
-      cmd << quote_and_escape("#{BATCH_FILE_DIR}#{executable}")
-      cmd << quote_and_escape("#{BATCH_FILE_DIR}#{script}")
-      cmd += args.map { |arg| quote_and_escape(replace_inst_dir_placeholder(arg)) }
+      cmd << quote_and_escape("#{BATCH_FILE_DIR}#{escape_percent(executable)}")
+      cmd << quote_and_escape("#{BATCH_FILE_DIR}#{escape_percent(script)}")
+      cmd += args.map { |arg| quote_and_escape(batch_value(arg, BATCH_FILE_DIR)) }
 
       # Forward batch file arguments to the command with `%*`
       cmd << "%*"

data/lib/ocran/npm_package.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+require "fileutils"
+require "json"
+require "timeout"
+require "pathname"
+
+module Ocran
+  # Fetches files out of a published npm package, which is how both
+  # ruby.wasm and PicoRuby distribute their browser runtimes: the prebuilt
+  # interpreter (.wasm) and the JavaScript that loads it.
+  #
+  # The package tarball is downloaded from the npm registry once, checked
+  # against the sha512 integrity the registry publishes for it, and the
+  # requested files are kept in OCRAN's cache directory, so later builds
+  # need no network. A cache filled by hand (the same layout) works offline
+  # from the start.
+  module NpmPackage
+    REGISTRY = "https://registry.npmjs.org"
+    MAX_REDIRECTS = 5
+
+    module_function
+
+    # Returns { file => absolute path } for the given files of the package
+    # (paths inside the package's tarball, without the leading "package/").
+    def fetch(name, version, files, &progress)
+      dir = File.join(cache_dir, name.delete_prefix("@").tr("/", "-"), version)
+      paths = files.to_h { |file| [file, File.join(dir, file)] }
+      return paths if paths.values.all? { |path| File.file?(path) }
+
+      progress&.call("Downloading #{name}@#{version} from the npm registry")
+      metadata = JSON.parse(download("#{REGISTRY}/#{name.sub("/", "%2f")}/#{version}"))
+      tarball = download(metadata.dig("dist", "tarball") || raise("the registry lists no tarball for #{name}@#{version}"))
+      verify(tarball, metadata.dig("dist", "integrity"), "#{name}@#{version}")
+      extract(tarball, files, dir)
+
+      missing = paths.reject { |_, path| File.file?(path) }.keys
+      raise "#{name}@#{version} does not contain #{missing.join(", ")}" unless missing.empty?
+
+      paths
+    rescue SocketError, SystemCallError, IOError, Timeout::Error, JSON::ParserError => e
+      raise "Could not download #{name}@#{version} from the npm registry (#{e.class}: #{e.message}). " \
+            "Without network access, put the package's #{files.join(", ")} into #{dir}"
+    end
+
+    def download(url, redirects = MAX_REDIRECTS)
+      require "net/http"
+      require "uri"
+
+      uri = URI(url)
+      response = Net::HTTP.get_response(uri)
+      case response
+      when Net::HTTPSuccess
+        response.body
+      when Net::HTTPRedirection
+        raise "too many redirects fetching #{url}" if redirects.zero?
+
+        download(URI.join(url, response["location"]).to_s, redirects - 1)
+      else
+        raise "#{url} answered #{response.code} #{response.message}"
+      end
+    end
+
+    def verify(data, integrity, what)
+      require "digest"
+
+      algorithm, expected = integrity.to_s.split("-", 2)
+      unless algorithm == "sha512" && expected
+        raise "the registry publishes no sha512 integrity for #{what}; refusing to use it unverified"
+      end
+      actual = Digest::SHA512.base64digest(data)
+      raise "#{what} does not match the integrity the registry publishes for it" unless actual == expected
+    end
+
+    def extract(tarball, files, dir)
+      require "rubygems/package"
+      require "stringio"
+      require "zlib"
+
+      wanted = files.to_h { |file| ["package/#{file}", file] }
+      FileUtils.mkdir_p(dir)
+      Zlib::GzipReader.wrap(StringIO.new(tarball)) do |gz|
+        Gem::Package::TarReader.new(gz) do |tar|
+          tar.each do |entry|
+            file = wanted[entry.full_name] or next
+
+            path = File.join(dir, file)
+            FileUtils.mkdir_p(File.dirname(path))
+            # Written under a temporary name first: a half-written file must
+            # not pass for a cached one.
+            File.binwrite("#{path}.part", entry.read)
+            File.rename("#{path}.part", path)
+          end
+        end
+      end
+    end
+
+    def cache_dir
+      base = ENV["XDG_CACHE_HOME"]
+      base = File.join(Dir.home, ".cache") if base.nil? || base.empty?
+      File.join(base, "ocran", "npm")
+    rescue ArgumentError # Dir.home unavailable (no HOME)
+      require "tmpdir"
+      File.join(Dir.tmpdir, "ocran-cache", "npm")
+    end
+  end
+end