Import the integrity hashes for packages from JSPM when pinning

And add a new command to download and add integrity hashes for packages.

Author: rafaelfranca

README.md

@@ -44,7 +44,7 @@ import React from "./node_modules/react"
 import React from "https://ga.jspm.io/npm:[email protected]/index.js"
 ```
 
-Importmap-rails provides a clean API for mapping "bare module specifiers" like `"react"` 
+Importmap-rails provides a clean API for mapping "bare module specifiers" like `"react"`
 to 1 of the 3 viable ways of loading ES Module javascript packages.
 
 For example:
@@ -54,11 +54,11 @@ For example:
 pin "react", to: "https://ga.jspm.io/npm:[email protected]/index.js"
 ```
 
-means "everytime you see `import React from "react"` 
+means "everytime you see `import React from "react"`
 change it to `import React from "https://ga.jspm.io/npm:[email protected]/index.js"`"
 
 ```js
-import React from "react" 
+import React from "react"
 // => import React from "https://ga.jspm.io/npm:[email protected]/index.js"
 ```
 
@@ -131,6 +131,91 @@ If you later wish to remove a downloaded pin:
 Unpinning and removing "react"
 ```
 
+## Subresource Integrity (SRI)
+
+For enhanced security, importmap-rails automatically includes [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hashes by default when pinning packages. This ensures that JavaScript files loaded from CDNs haven't been tampered with.
+
+### Default behavior with integrity
+
+When you pin a package, integrity hashes are automatically included:
+
+```bash
+./bin/importmap pin lodash
+Pinning "lodash" to vendor/javascript/lodash.js via download from https://ga.jspm.io/npm:[email protected]/lodash.js
+  Using integrity: sha384-PkIkha4kVPRlGtFantHjuv+Y9mRefUHpLFQbgOYUjzy247kvi16kLR7wWnsAmqZF
+```
+
+This generates a pin in your `config/importmap.rb` with the integrity hash:
+
+```ruby
+pin "lodash", integrity: "sha384-PkIkha4kVPRlGtFantHjuv+Y9mRefUHpLFQbgOYUjzy247kvi16kLR7wWnsAmqZF" # @4.17.21
+```
+
+### Opting out of integrity
+
+If you need to disable integrity checking (not recommended for security reasons), you can use the `--no-integrity` flag:
+
+```bash
+./bin/importmap pin lodash --no-integrity
+Pinning "lodash" to vendor/javascript/lodash.js via download from https://ga.jspm.io/npm:[email protected]/lodash.js
+```
+
+This generates a pin without integrity:
+
+```ruby
+pin "lodash" # @4.17.21
+```
+
+### Adding integrity to existing pins
+
+If you have existing pins without integrity hashes, you can add them using the `integrity` command:
+
+```bash
+# Add integrity to specific packages
+./bin/importmap integrity lodash react
+
+# Add integrity to all pinned packages
+./bin/importmap integrity
+
+# Update your importmap.rb file with integrity hashes
+./bin/importmap integrity --update
+```
+
+### How integrity works
+
+The integrity hashes are automatically included in your import map and module preload tags:
+
+**Import map JSON:**
+```json
+{
+  "imports": {
+    "lodash": "https://ga.jspm.io/npm:[email protected]/lodash.js"
+  },
+  "integrity": {
+    "https://ga.jspm.io/npm:[email protected]/lodash.js": "sha384-PkIkha4kVPRlGtFantHjuv+Y9mRefUHpLFQbgOYUjzy247kvi16kLR7wWnsAmqZF"
+  }
+}
+```
+
+**Module preload tags:**
+```html
+<link rel="modulepreload" href="https://ga.jspm.io/npm:[email protected]/lodash.js" integrity="sha384-PkIkha4kVPRlGtFantHjuv+Y9mRefUHpLFQbgOYUjzy247kvi16kLR7wWnsAmqZF">
+```
+
+Modern browsers will automatically validate these integrity hashes when loading the JavaScript modules, ensuring the files haven't been modified.
+
+### Redownloading packages with integrity
+
+The `pristine` command also includes integrity by default:
+
+```bash
+# Redownload all packages with integrity (default)
+./bin/importmap pristine
+
+# Redownload packages without integrity
+./bin/importmap pristine --no-integrity
+```
+
 ## Preloading pinned modules
 
 To avoid the waterfall effect where the browser has to load one file after another before it can get to the deepest nested import, importmap-rails uses [modulepreload links](https://developers.google.com/web/updates/2017/12/modulepreload) by default. If you don't want to preload a dependency, because you want to load it on-demand for efficiency, append `preload: false` to the pin.

lib/importmap/commands.rb

@@ -13,55 +13,51 @@ def self.exit_on_failure?
   option :env, type: :string, aliases: :e, default: "production"
   option :from, type: :string, aliases: :f, default: "jspm"
   option :preload, type: :string, repeatable: true, desc: "Can be used multiple times"
+  option :integrity, type: :boolean, aliases: :i, default: true, desc: "Include integrity hash from JSPM"
   def pin(*packages)
-    if imports = packager.import(*packages, env: options[:env], from: options[:from])
-      imports.each do |package, url|
+    with_import_response(packages, env: options[:env], from: options[:from], integrity: options[:integrity]) do |imports, integrity_hashes|
+      process_imports(imports, integrity_hashes) do |package, url, integrity_hash|
         puts %(Pinning "#{package}" to #{packager.vendor_path}/#{package}.js via download from #{url})
+
         packager.download(package, url)
-        pin = packager.vendored_pin_for(package, url, options[:preload])
 
-        if packager.packaged?(package)
-          gsub_file("config/importmap.rb", /^pin "#{package}".*$/, pin, verbose: false)
-        else
-          append_to_file("config/importmap.rb", "#{pin}\n", verbose: false)
-        end
+        pin = packager.vendored_pin_for(package, url, options[:preload], integrity: integrity_hash)
+
+        log_integrity_usage(integrity_hash)
+        update_importmap_with_pin(package, pin)
       end
-    else
-      puts "Couldn't find any packages in #{packages.inspect} on #{options[:from]}"
     end
   end
 
   desc "unpin [*PACKAGES]", "Unpin existing packages"
   option :env, type: :string, aliases: :e, default: "production"
   option :from, type: :string, aliases: :f, default: "jspm"
   def unpin(*packages)
-    if imports = packager.import(*packages, env: options[:env], from: options[:from])
+    with_import_response(packages, env: options[:env], from: options[:from]) do |imports, _integrity_hashes|
       imports.each do |package, url|
         if packager.packaged?(package)
           puts %(Unpinning and removing "#{package}")
           packager.remove(package)
         end
       end
-    else
-      puts "Couldn't find any packages in #{packages.inspect} on #{options[:from]}"
     end
   end
 
   desc "pristine", "Redownload all pinned packages"
   option :env, type: :string, aliases: :e, default: "production"
   option :from, type: :string, aliases: :f, default: "jspm"
+  option :integrity, type: :boolean, aliases: :i, default: true, desc: "Include integrity hash from JSPM"
   def pristine
-    packages = npm.packages_with_versions.map do |p, v|
-      v.blank? ? p : [p, v].join("@")
-    end
+    packages = prepare_packages_with_versions
 
-    if imports = packager.import(*packages, env: options[:env], from: options[:from])
-      imports.each do |package, url|
+    with_import_response(packages, env: options[:env], from: options[:from], integrity: options[:integrity]) do |imports, integrity_hashes|
+      process_imports(imports, integrity_hashes) do |package, url, integrity_hash|
         puts %(Downloading "#{package}" to #{packager.vendor_path}/#{package}.js from #{url})
+
         packager.download(package, url)
+
+        log_integrity_usage(integrity_hash)
       end
-    else
-      puts "Couldn't find any packages in #{packages.inspect} on #{options[:from]}"
     end
   end
 
@@ -122,6 +118,33 @@ def packages
     puts npm.packages_with_versions.map { |x| x.join(' ') }
   end
 
+  desc "integrity [*PACKAGES]", "Download and add integrity hashes for packages"
+  option :env, type: :string, aliases: :e, default: "production"
+  option :from, type: :string, aliases: :f, default: "jspm"
+  option :update, type: :boolean, aliases: :u, default: false, desc: "Update importmap.rb with integrity hashes"
+  def integrity(*packages)
+    packages = prepare_packages_with_versions(packages)
+
+    with_import_response(packages, env: options[:env], from: options[:from], integrity: true) do |imports, integrity_hashes|
+      process_imports(imports, integrity_hashes) do |package, url, integrity_hash|
+        puts %(Getting integrity for "#{package}" from #{url})
+
+        if integrity_hash
+          puts %(  #{package}: #{integrity_hash})
+
+          if options[:update]
+            pin_with_integrity = packager.pin_for(package, url, integrity: integrity_hash)
+
+            update_importmap_with_pin(package, pin_with_integrity)
+            puts %(  Updated importmap.rb with integrity for "#{package}")
+          end
+        else
+          puts %(  No integrity hash available for "#{package}")
+        end
+      end
+    end
+  end
+
   private
     def packager
       @packager ||= Importmap::Packager.new
@@ -131,6 +154,22 @@ def npm
       @npm ||= Importmap::Npm.new
     end
 
+    def update_importmap_with_pin(package, pin)
+      if packager.packaged?(package)
+        gsub_file("config/importmap.rb", /^pin "#{package}".*$/, pin, verbose: false)
+      else
+        append_to_file("config/importmap.rb", "#{pin}\n", verbose: false)
+      end
+    end
+
+    def log_integrity_usage(integrity_hash)
+      puts %(  Using integrity: #{integrity_hash}) if integrity_hash
+    end
+
+    def handle_package_not_found(packages, from)
+      puts "Couldn't find any packages in #{packages.inspect} on #{from}"
+    end
+
     def remove_line_from_file(path, pattern)
       path = File.expand_path(path, destination_root)
 
@@ -155,6 +194,33 @@ def puts_table(array)
         puts divider if row_number == 0
       end
     end
+
+    def prepare_packages_with_versions(packages = [])
+      if packages.empty?
+        npm.packages_with_versions.map do |p, v|
+          v.blank? ? p : [p, v].join("@")
+        end
+      else
+        packages
+      end
+    end
+
+    def process_imports(imports, integrity_hashes, &block)
+      imports.each do |package, url|
+        integrity_hash = integrity_hashes[url]
+        block.call(package, url, integrity_hash)
+      end
+    end
+
+    def with_import_response(packages, **options)
+      response = packager.import(*packages, **options)
+
+      if response
+        yield response[:imports], response[:integrity]
+      else
+        handle_package_not_found(packages, options[:from])
+      end
+    end
 end
 
 Importmap::Commands.start(ARGV)

lib/importmap/packager.rb

@@ -17,34 +17,39 @@ def initialize(importmap_path = "config/importmap.rb", vendor_path: "vendor/java
     @vendor_path    = Pathname.new(vendor_path)
   end
 
-  def import(*packages, env: "production", from: "jspm")
+  def import(*packages, env: "production", from: "jspm", integrity: false)
     response = post_json({
       "install"      => Array(packages),
       "flattenScope" => true,
       "env"          => [ "browser", "module", env ],
-      "provider"     => normalize_provider(from)
+      "provider"     => normalize_provider(from),
+      "integrity"    => integrity
     })
 
     case response.code
-    when "200"        then extract_parsed_imports(response)
-    when "404", "401" then nil
-    else                   handle_failure_response(response)
+    when "200"
+      extract_parsed_response(response)
+    when "404", "401"
+      nil
+    else
+      handle_failure_response(response)
     end
   end
 
-  def pin_for(package, url)
-    %(pin "#{package}", to: "#{url}")
+  def pin_for(package, url = nil, preloads: nil, integrity: nil)
+    to = url ? %(, to: "#{url}") : ""
+    preload_param = preload(preloads)
+    integrity_param = integrity ? %(, integrity: "#{integrity}") : ""
+
+     %(pin "#{package}") + to + preload_param + integrity_param
   end
 
-  def vendored_pin_for(package, url, preloads = nil)
+  def vendored_pin_for(package, url, preloads = nil, integrity: nil)
     filename = package_filename(package)
     version  = extract_package_version_from(url)
+    to = "#{package}.js" != filename ? filename : nil
 
-    if "#{package}.js" == filename
-      %(pin "#{package}"#{preload(preloads)} # #{version})
-    else
-      %(pin "#{package}", to: "#{filename}"#{preload(preloads)} # #{version})
-    end
+    pin_for(package, to, preloads: preloads, integrity: integrity) + %( # #{version})
   end
 
   def packaged?(package)
@@ -88,8 +93,15 @@ def normalize_provider(name)
       name.to_s == "jspm" ? "jspm.io" : name.to_s
     end
 
-    def extract_parsed_imports(response)
-      JSON.parse(response.body).dig("map", "imports")
+    def extract_parsed_response(response)
+      parsed = JSON.parse(response.body)
+      imports = parsed.dig("map", "imports")
+      integrity = parsed.dig("map", "integrity") || {}
+
+      {
+        imports: imports,
+        integrity: integrity
+      }
     end
 
     def handle_failure_response(response)