al_folio_distill 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e85ca554399308d28af93a3d025b0d70c46b9d057563236682ce17382eecf8cd
-  data.tar.gz: bf90c691657352a5c90b0d74381a73b37cfcc00ede4fc459aefe7d8e437eacb7
+  metadata.gz: 43e18fcf0822a90ad412005985178d449d7267f6924b38b3181aba3edf176cff
+  data.tar.gz: 1d2a83960addd942b34e39891854356b906d9380ff748252fab0a15cf6eb90fc
 SHA512:
-  metadata.gz: df094843f4a0943e5e621b1346700580e7b030f1b12a85e5c739fd81760e9405ab395eea913ce7b170dfaf8b2c22aa094ba339f7f0085f91a18cc5fa801ed44d
-  data.tar.gz: 25fc0a770e18e5c31c57bb22727061dc69a0262d998ff465ece6acc73489499a8c90fba065d47e225dc6aa1d981c682c8d833b6c931ff88eeea40f07e907f7f0
+  metadata.gz: e75ede64f8075366893d771808ba5840c957ffb75d92f328a166f2361caf8ad63af727c41e94f4e7398443bd62438451e9ca1f82be2d40d1c70394c137c927cd
+  data.tar.gz: cbfd8b4eabf21748c1a5267566f675bbc49c5bde027cb2867614dcfc7b317456a85a941fdcbd0288cda91608968ce565d2bd5148f0ced73652e97851765bb7e4

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.0.3 - 2026-07-27
+
+- Security: removed the unpinned remote Distill runtime loader. The vendored `assets/js/distillpub/transforms.v2.js` shipped upstream's `Polyfills` transform, which strips the page's `template.v2.js` tag and re-injects it from a hard-coded `https://distill.pub/template.v2.js` with no subresource integrity — discarding the vendored, hash-pinned copy this gem exists to ship and handing arbitrary JS execution on every Distill page to whoever controls that origin. The transform now re-injects `window.alFolioDistill.templateLoader`, falling back to the same-origin `src` of the tag it just removed, and never falls back to a remote origin. Recorded under `local_patches` and flipped `remote_loader_patched` to `true` (port it to the upstream distill-template so a future re-sync preserves it).
+- `templates/distill/render.liquid` now emits the runtime via the new `{% al_folio_distill_runtime_scripts %}` tag, which serves `template.v2.js`/`transforms.v2.js` from the vendored copy with `integrity` pinned to the SHA-256 digests committed in `provenance.json`.
+- Remote loading is now explicit opt-in via `al_folio.distill.allow_remote_loader` (default `false`), with `al_folio.distill.remote_loader_url` and `al_folio.distill.remote_loader_integrity`. When an SRI hash is configured the injected tag carries `integrity` + `crossorigin="anonymous"`; the build warns when opting in without one.
+- Added a build-time check that the vendored runtime on disk matches the digests pinned in `provenance.json`, so drift is reported at build time instead of failing subresource integrity in visitors' browsers.
+- `scripts/distill/sync_distill.sh` now derives `remote_loader_patched` from the synced bytes instead of hard-coding `false`, preserves `local_patches`, and exits non-zero if a re-sync reintroduces the remote loader.
+
 ## 1.0.2 - 2026-06-01
 
 - De-jQueried the vendored `assets/js/distillpub/overrides.js`. Its top-level `$(window).on("load", ...)` threw `ReferenceError: $ is not defined` on every distill page (jQuery was removed in al-folio v1), so the footnote/citation dark-theme overrides never applied and the page logged a console error. Switched to `window.addEventListener("load", ...)`; the handler body was already vanilla. Updated the pinned SHA-256 in `provenance.json` and the runtime contract test, and recorded the change under `local_patches` (port it to the upstream distill-template so a future re-sync preserves it).

data/README.md

@@ -42,6 +42,37 @@ Refresh assets:
 ./scripts/distill/sync_distill.sh <commit-sha>
 ```
 
+The sync script records the real digests in `provenance.json` and fails if the
+synced ref reintroduces the hard-coded remote Distill loader (see below).
+
+## Runtime loading policy
+
+Distill pages load the runtime from the vendored copy under
+`/assets/js/distillpub/`, with `integrity` pinned to the SHA-256 digests
+committed in `provenance.json`. Upstream's `Polyfills` transform removes the
+page's template tag and re-adds it; the vendored copy is patched so it re-adds
+the vendored URL rather than a hard-coded `distill.pub` one.
+
+Loading the runtime from a third-party origin is opt-in:
+
+```yaml
+al_folio:
+  distill:
+    engine: distillpub-template
+    source: al-org-dev/distill-template#al-folio
+    # Default false. When false, the runtime is only ever loaded from the
+    # vendored, integrity-pinned copy.
+    allow_remote_loader: false
+    # Only used when allow_remote_loader is true.
+    remote_loader_url: https://distill.pub/template.v2.js
+    # Optional SRI for remote_loader_url. When set, the injected tag carries
+    # integrity + crossorigin="anonymous". The build warns when it is missing.
+    remote_loader_integrity: sha256-...
+```
+
+Keep `allow_remote_loader: false` unless you control the remote origin: whoever
+serves `remote_loader_url` executes arbitrary JavaScript on every Distill page.
+
 ## Contributing
 
 Distill runtime/template behavior belongs here. Starter-only docs/demo changes belong in `al-folio`.

data/assets/js/distillpub/provenance.json

@@ -7,13 +7,14 @@
   "toolchain": {
     "sync_mode": "copy-dist-artifacts"
   },
-  "remote_loader_patched": false,
+  "remote_loader_patched": true,
   "local_patches": [
-    "overrides.js: de-jQuery the load handler ($(window).on('load', ...) -> window.addEventListener('load', ...)); jQuery is not loaded in al-folio v1. Port this upstream so the next sync preserves it."
+    "overrides.js: de-jQuery the load handler ($(window).on('load', ...) -> window.addEventListener('load', ...)); jQuery is not loaded in al-folio v1. Port this upstream so the next sync preserves it.",
+    "transforms.v2.js: the Polyfills transform re-injected the runtime from a hard-coded remote distill.pub template URL with no SRI, discarding the vendored copy. It now re-injects window.alFolioDistill.templateLoader (vendored + integrity-pinned by default), falling back to the same-origin src of the tag it removed. Port this upstream so the next sync preserves it."
   ],
   "assets": {
     "template.v2.js": "4790831ced02f7c4f2009b2cdf6978ceda8351f0060d3b59dd9b3aab132e271a",
-    "transforms.v2.js": "70e3f488e23ec379d33a10a60311ec60b570b3b2d5f1823e9159f661c315184e",
+    "transforms.v2.js": "5d85590f5652b910ab2411019749c83ef5a5a3fbb9b739adc92b4557b6bf3d39",
     "overrides.js": "41ce4a3744a9083e8913df1256432d2233ba16ff9b40c4878bdb3f35d73c0e8e"
   }
 }

data/assets/js/distillpub/transforms.v2.js

@@ -14060,11 +14060,31 @@
   //
   // `;
 
-  const addBackIn = `
+  // al-folio local patch: upstream re-injects the Distill runtime from a
+  // hard-coded remote distill.pub template URL with no subresource integrity,
+  // which silently discards the vendored, hash-pinned copy this gem ships.
+  // Re-inject the loader al-folio declared instead
+  // (`window.alFolioDistill.templateLoader`, emitted by
+  // templates/distill/render.liquid), falling back to the same-origin src of the
+  // tag we just removed. Never fall back to a remote origin.
+  const addBackIn = (templateSrc) => `
 window.addEventListener('WebComponentsReady', function() {
   console.warn('WebComponentsReady');
-  const loaderTag = document.createElement('script');
-  loaderTag.src = 'https://distill.pub/template.v2.js';
+  var loader = (window.alFolioDistill && window.alFolioDistill.templateLoader) || {};
+  var fallbackSrc = ${JSON.stringify(templateSrc)};
+  var loaderTag = document.createElement('script');
+  if (loader.url) {
+    loaderTag.src = loader.url;
+    if (loader.integrity) {
+      loaderTag.integrity = loader.integrity;
+      loaderTag.crossOrigin = 'anonymous';
+    }
+  } else if (fallbackSrc) {
+    loaderTag.src = fallbackSrc;
+  } else {
+    console.error('al_folio_distill: no Distill template URL configured; refusing to load the runtime from a remote origin.');
+    return;
+  }
   document.head.insertBefore(loaderTag, document.head.firstChild);
 });
 `;
@@ -14072,7 +14092,9 @@ window.addEventListener('WebComponentsReady', function() {
   function render(dom) {
     // pull out template script tag
     const templateTag = dom.querySelector('script[src*="template.v2.js"]');
+    let templateSrc = null;
     if (templateTag) {
+      templateSrc = templateTag.getAttribute("src");
       templateTag.parentNode.removeChild(templateTag);
     } else {
       console.debug("FYI: Did not find template tag when trying to remove it. You may not have added it. Be aware that our polyfills will add it.");
@@ -14085,7 +14107,7 @@ window.addEventListener('WebComponentsReady', function() {
 
     // add loader event listener to add tempalrte back in
     const addTag = dom.createElement("script");
-    addTag.innerHTML = addBackIn;
+    addTag.innerHTML = addBackIn(templateSrc);
     dom.head.insertBefore(addTag, dom.head.firstChild);
 
     // create polyfill script tag

data/lib/al_folio_distill/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AlFolioDistill
-  VERSION = "1.0.2"
+  VERSION = "1.0.3"
 end

data/lib/al_folio_distill.rb

@@ -1,13 +1,21 @@
 # frozen_string_literal: true
 
 require "jekyll"
+require "digest"
+require "json"
 require_relative "al_folio_distill/version"
 
 module AlFolioDistill
   PLUGIN_ROOT = File.expand_path("..", __dir__)
   TEMPLATES_ROOT = File.join(PLUGIN_ROOT, "templates")
   ASSETS_ROOT = File.join(PLUGIN_ROOT, "assets")
+  RUNTIME_ROOT = File.join(ASSETS_ROOT, "js", "distillpub")
+  RUNTIME_URL_PREFIX = "/assets/js/distillpub"
+  PROVENANCE_PATH = File.join(RUNTIME_ROOT, "provenance.json")
   DISTILL_REMOTE_LOADER_PATTERN = %r{https://distill\.pub/template\.v2\.js}
+  DEFAULT_REMOTE_LOADER_URL = "https://distill.pub/template.v2.js"
+  RUNTIME_SCRIPTS = ["template.v2.js", "transforms.v2.js"].freeze
+  SHA256_HEX_PATTERN = /\A[0-9a-f]{64}\z/.freeze
 
   class PluginStaticFile < Jekyll::StaticFile; end
 
@@ -21,6 +29,51 @@ module AlFolioDistill
     site.config.dig("al_folio", "distill", "allow_remote_loader") == true
   end
 
+  def remote_loader_url(site)
+    configured = site.config.dig("al_folio", "distill", "remote_loader_url")
+    configured.is_a?(String) && !configured.empty? ? configured : DEFAULT_REMOTE_LOADER_URL
+  end
+
+  def remote_loader_integrity(site)
+    configured = site.config.dig("al_folio", "distill", "remote_loader_integrity")
+    configured if configured.is_a?(String) && !configured.empty?
+  end
+
+  # Committed, known-good digests for the vendored runtime. Refreshed by
+  # `scripts/distill/sync_distill.sh`; asserted by the runtime contract test.
+  def provenance
+    @provenance ||= File.file?(PROVENANCE_PATH) ? JSON.parse(File.read(PROVENANCE_PATH)) : {}
+  rescue JSON::ParserError => e
+    Jekyll.logger.warn("al_folio_distill:", "could not parse provenance.json (#{e.message}); runtime integrity pinning is disabled")
+    @provenance = {}
+  end
+
+  def pinned_digest(asset)
+    digest = provenance.dig("assets", asset)
+    digest if digest.is_a?(String) && digest.match?(SHA256_HEX_PATTERN)
+  end
+
+  # Subresource Integrity wants base64, provenance.json pins hex. Same bytes.
+  def integrity_for(asset)
+    digest = pinned_digest(asset)
+    digest && "sha256-#{[[digest].pack("H*")].pack("m0")}"
+  end
+
+  def runtime_url(site, asset)
+    "#{site.config["baseurl"].to_s.chomp("/")}#{RUNTIME_URL_PREFIX}/#{asset}"
+  end
+
+  # Describes where the Distill runtime may be re-injected from after the
+  # polyfill transform strips the original tag. Local + pinned unless a site
+  # explicitly opts into a remote origin.
+  def template_loader(site)
+    if remote_loader_allowed?(site)
+      { "url" => remote_loader_url(site), "integrity" => remote_loader_integrity(site), "remote" => true }.compact
+    else
+      { "url" => runtime_url(site, "template.v2.js"), "integrity" => integrity_for("template.v2.js"), "remote" => false }.compact
+    end
+  end
+
   class AssetsGenerator < Jekyll::Generator
     safe true
     priority :low
@@ -48,9 +101,48 @@ module AlFolioDistill
       )
     end
   end
+
+  # Emits the vendored Distill runtime with integrity pinned to the committed
+  # provenance digests, plus the loader descriptor the patched polyfill
+  # transform reads when it re-injects the template tag.
+  class RuntimeScriptsTag < Liquid::Tag
+    def render(context)
+      site = context.registers[:site]
+      return "" unless site && AlFolioDistill.enabled?(site)
+
+      lines = [
+        "<script>",
+        "  window.alFolioDistill = window.alFolioDistill || {};",
+        "  window.alFolioDistill.templateLoader = #{json_literal(AlFolioDistill.template_loader(site))};",
+        "</script>",
+      ]
+      AlFolioDistill::RUNTIME_SCRIPTS.each do |asset|
+        lines << script_tag(AlFolioDistill.runtime_url(site, asset), AlFolioDistill.integrity_for(asset))
+      end
+      lines.join("\n")
+    end
+
+    private
+
+    def script_tag(url, integrity)
+      attributes = %(src="#{escape(url)}")
+      attributes += %( integrity="#{escape(integrity)}") if integrity
+      "<script #{attributes}></script>"
+    end
+
+    # Inline JSON must never be able to close the surrounding <script> element.
+    def json_literal(value)
+      JSON.generate(value).gsub("</", '<\/')
+    end
+
+    def escape(value)
+      value.to_s.gsub("&", "&amp;").gsub('"', "&quot;").gsub("<", "&lt;").gsub(">", "&gt;")
+    end
+  end
 end
 
 Liquid::Template.register_tag("al_folio_distill_render", AlFolioDistill::RenderTag)
+Liquid::Template.register_tag("al_folio_distill_runtime_scripts", AlFolioDistill::RuntimeScriptsTag)
 
 Jekyll::Hooks.register :site, :after_init do |site|
   next unless site.respond_to?(:includes_load_paths)
@@ -61,12 +153,36 @@ end
 
 Jekyll::Hooks.register :site, :post_read do |site|
   next unless AlFolioDistill.enabled?(site)
-  next if AlFolioDistill.remote_loader_allowed?(site)
 
-  transforms_path = File.join(AlFolioDistill::ASSETS_ROOT, "js", "distillpub", "transforms.v2.js")
+  # The served bytes must match the digests we pin in the emitted `integrity`
+  # attributes, otherwise every Distill page fails SRI in the browser.
+  AlFolioDistill::RUNTIME_SCRIPTS.each do |asset|
+    pinned = AlFolioDistill.pinned_digest(asset)
+    asset_path = File.join(AlFolioDistill::RUNTIME_ROOT, asset)
+    next unless pinned && File.file?(asset_path)
+    next if Digest::SHA256.file(asset_path).hexdigest == pinned
+
+    Jekyll.logger.warn(
+      "al_folio_distill:",
+      "vendored #{asset} does not match the digest pinned in provenance.json; Distill pages will fail subresource integrity"
+    )
+  end
+
+  if AlFolioDistill.remote_loader_allowed?(site)
+    unless AlFolioDistill.remote_loader_integrity(site)
+      Jekyll.logger.warn(
+        "al_folio_distill:",
+        "`al_folio.distill.allow_remote_loader` is true without `al_folio.distill.remote_loader_integrity`; " \
+          "the Distill runtime will be loaded from #{AlFolioDistill.remote_loader_url(site)} without subresource integrity"
+      )
+    end
+    next
+  end
+
+  transforms_path = File.join(AlFolioDistill::RUNTIME_ROOT, "transforms.v2.js")
   next unless File.file?(transforms_path)
 
-  content = File.read(transforms_path)
+  content = File.read(transforms_path, encoding: "UTF-8")
   if content.match?(AlFolioDistill::DISTILL_REMOTE_LOADER_PATTERN)
     Jekyll.logger.warn("al_folio_distill:", "remote Distill template loader detected while `al_folio.distill.allow_remote_loader` is false")
   end

data/scripts/distill/sync_distill.sh

@@ -49,6 +49,16 @@ TEMPLATE_SHA256="$(shasum -a 256 "${OUT_DIR}/template.v2.js" | awk '{print $1}')
 TRANSFORMS_SHA256="$(shasum -a 256 "${OUT_DIR}/transforms.v2.js" | awk '{print $1}')"
 SYNCED_AT_UTC="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
 
+# The upstream Polyfills transform re-injects the Distill runtime from a
+# hard-coded remote origin with no subresource integrity, which discards the
+# vendored copy we just pinned. Report the real state instead of assuming it.
+REMOTE_LOADER_URL="https://distill.pub/template.v2.js"
+if grep -qF "${REMOTE_LOADER_URL}" "${OUT_DIR}/transforms.v2.js"; then
+  REMOTE_LOADER_PATCHED="false"
+else
+  REMOTE_LOADER_PATCHED="true"
+fi
+
 cat > "${OUT_DIR}/provenance.json" <<JSON
 {
   "upstream_repo": "${UPSTREAM_REPO}",
@@ -59,7 +69,11 @@ cat > "${OUT_DIR}/provenance.json" <<JSON
   "toolchain": {
     "sync_mode": "copy-dist-artifacts"
   },
-  "remote_loader_patched": false,
+  "remote_loader_patched": ${REMOTE_LOADER_PATCHED},
+  "local_patches": [
+    "overrides.js: de-jQuery the load handler (\$(window).on('load', ...) -> window.addEventListener('load', ...)); jQuery is not loaded in al-folio v1. Port this upstream so the next sync preserves it.",
+    "transforms.v2.js: the Polyfills transform re-injected the runtime from a hard-coded remote distill.pub template URL with no SRI, discarding the vendored copy. It now re-injects window.alFolioDistill.templateLoader (vendored + integrity-pinned by default), falling back to the same-origin src of the tag it removed. Port this upstream so the next sync preserves it."
+  ],
   "assets": {
     "template.v2.js": "${TEMPLATE_SHA256}",
     "transforms.v2.js": "${TRANSFORMS_SHA256}",
@@ -70,3 +84,17 @@ JSON
 
 echo "Synced Distill runtime from ${UPSTREAM_REPO}@${SOURCE_COMMIT}"
 echo "Updated assets in ${OUT_DIR}"
+
+if [ "${REMOTE_LOADER_PATCHED}" = "false" ]; then
+  cat >&2 <<MSG
+
+ERROR: ${OUT_DIR}/transforms.v2.js still hard-codes ${REMOTE_LOADER_URL}.
+
+The synced ref reintroduced the unpinned remote Distill loader, so Distill pages
+would fetch the runtime from a third-party origin with no subresource integrity
+instead of the vendored copy. Land the loader patch listed under "local_patches"
+in ${UPSTREAM_REPO} (${UPSTREAM_BRANCH}) and re-sync, or re-apply it by hand and
+refresh the digests in provenance.json.
+MSG
+  exit 1
+fi

data/templates/distill/render.liquid

@@ -4,9 +4,8 @@
     {% include head.liquid %}
     <link rel="stylesheet" href="{{ '/assets/css/al-folio-distill.css' | relative_url | bust_file_cache }}">
 
-    <!-- Distill js -->
-    <script src="{{ '/assets/js/distillpub/template.v2.js' | relative_url }}"></script>
-    <script src="{{ '/assets/js/distillpub/transforms.v2.js' | relative_url }}"></script>
+    <!-- Distill js (vendored + integrity-pinned; see assets/js/distillpub/provenance.json) -->
+    {% al_folio_distill_runtime_scripts %}
     {% if page._styles %}
       <!-- Page/Post style -->
       <style type="text/css">

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: al_folio_distill
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - al-folio maintainers
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -127,6 +128,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/al-org-dev/al-folio-distill
   source_code_uri: https://github.com/al-org-dev/al-folio-distill
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -141,7 +143,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Distill rendering plugin for al-folio v1.x
 test_files: []