Add Subresource Integrity (SRI) verification for remote stylesheets by JLLeitschuh · Pull Request #190 · premailer/css_parser

JLLeitschuh · 2026-09-01T20:49:45Z

What

Adds an integrity: option to Parser#load_uri! that verifies a fetched remote stylesheet against a Subresource Integrity value before it's parsed — the same value an HTML <link integrity="..."> attribute carries.

parser.load_uri!(
  'http://example.com/styles/style.css',
  integrity: 'sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC'
)

Supports sha256/sha384/sha512, multiple space-separated values in one integrity: string (exactly like the HTML attribute), and the spec's "agility" rule: when a value lists more than one algorithm, only the strongest present one is actually checked, and every weaker one is ignored outright — e.g. sha256-... sha384-... only checks the sha384 value. When several values are given for that same strongest algorithm (e.g. during a planned key/stylesheet rotation), matching any one of them is enough.
A value naming only an algorithm this library doesn't recognize is treated as unverifiable (passes through) rather than failing every such fetch.
On mismatch, the fetch fails the same way other remote-fetch failures already do here: raises CssParser::RemoteFileError when io_exceptions is enabled, otherwise loads nothing.

Why

Consumers of this gem that already know the expected digest of a linked stylesheet (for example, because it came from an HTML <link integrity="..."> attribute they're processing) currently have no way to ask load_uri! to verify it — the fetched body is trusted unconditionally regardless of what the caller expected. This gives callers an opt-in way to fail closed instead.

Testing

New test/test_css_parser_integrity.rb, covering: normal pass-through when the option is omitted, all three supported algorithms, mismatch handling (with and without io_exceptions), the multi-algorithm "agility" rule in both directions (weaker-correct+stronger-wrong fails, weaker-wrong+stronger-correct passes), multiple acceptable values for one algorithm, and the unsupported-algorithm-is-unverifiable case.
Full existing suite passes (bundle exec rake test) — no behavior change when integrity: isn't passed.
bundle exec rubocop clean on the changed files.

Happy to adjust the option name/shape or add doc updates elsewhere if you'd rather it live somewhere other than load_uri!.

Adds an `integrity:` option to `Parser#load_uri!` that verifies a fetched remote stylesheet against a Subresource Integrity value (https://www.w3.org/TR/SRI/) before it is parsed, mirroring the `integrity` attribute browsers already support on `<link>`/`<script>` tags. Supports sha256/sha384/sha512, multiple space-separated values, and the SRI "agility" rule (only the strongest present algorithm is checked). A value naming only an unrecognized algorithm is treated as unverifiable rather than failing the fetch. On mismatch, the fetch fails the same way other remote-fetch failures already do: raises CssParser::RemoteFileError when io_exceptions is enabled, otherwise loads nothing. Useful for any caller that already knows the expected digest of a linked stylesheet and wants a stale or unexpectedly-changed response to fail closed rather than be silently parsed and applied. Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Ruby 3.4+ removed `base64` from default gems (it's now a bundled gem that must be an explicit dependency to be resolvable). `require 'base64'` in parser.rb was relying on it still being present by default, which breaks under Ruby 4.0 CI with a LoadError. Declare it in the gemspec. Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

JLLeitschuh · 2026-09-01T20:55:41Z

Fixed — Ruby 3.4+/4.0 removed base64 from default gems, so require 'base64' needs it declared as an explicit runtime dependency. Added s.add_dependency 'base64' and updated Gemfile.lock accordingly. Full suite + rubocop pass locally on 3.3.9; should now pass on the 4.0 CI job too.

JLLeitschuh · 2026-09-01T21:06:09Z

Re: the JRuby job failure (CssParserOffsetCaptureTests#test_capturing_offsets_from_remote_file, RemoteFileError: https://dialect.ca/inc/screen.css) — that's pre-existing and unrelated to this PR:

It reproduces identically against unmodified master (I hit the same error before making any changes here).
The test never passes the new integrity: option, so this PR's new code path isn't reached by it at all.
The test itself is unchanged since 2021 (3a3b21e) and makes a live network call to a real third-party site — dialect.ca/inc/screen.css is reachable right now, so it's not permanently dead, just flaky in CI (possibly a JRuby/JVM TLS-stack quirk against that host, since JRuby uses its own TLS implementation rather than MRI's OpenSSL, per this repo's "Drop jruby-openssl dependency" history).

Flagging so it's not mistaken for a regression from this change.

Adds a second README example showing the multi-value/multi-algorithm form of the `integrity:` option (as SRI itself allows), since the existing example only showed a single sha384 value and didn't make the "strongest algorithm wins" behavior visible without reading the implementation. Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

grosser · 2026-09-05T17:29:00Z

+    # Subresource Integrity value -- a single `<algorithm>-<base64 digest>` token, or
+    # several whitespace-separated tokens (https://www.w3.org/TR/SRI/#the-integrity-attribute).
+    # Tokens using an algorithm this library doesn't recognize are ignored; per the spec's
+    # "agility" rule, when multiple recognized algorithms are present only the strongest one


why the strongest and not the first ?

grosser · 2026-09-05T17:30:42Z

+      digest_class = {
+        'sha512' => Digest::SHA512,
+        'sha384' => Digest::SHA384,
+        'sha256' => Digest::SHA256
+      }.fetch(algorithm)


how about we make INTEGRITY_ALGORITHM_PRIORITY = {"sha512" => [0, Digest::SHA512], ...} so we don't have 2 different structures that need to be in sync

grosser · 2026-09-05T17:32:49Z

+      return true if candidates.empty?
+
+      algorithm = candidates.map(&:first).min_by { |a| INTEGRITY_ALGORITHM_PRIORITY.index(a) }
+      expected_values = candidates.select { |a, _v| a == algorithm }.map { |_a, v| v }


multiple values for the same algorithm is expected ?

grosser · 2026-09-05T17:34:01Z

 # load a remote file, setting the base_uri and media_types
 parser.load_uri!('../style.css', {base_uri: 'http://example.com/styles/inc/', media_types: [:screen, :handheld]})

+# load a remote file, verifying it against a Subresource Integrity value


doubt many ppl will use this, so put it further at the back + in it's own section

grosser · 2026-09-05T17:34:27Z

        end

+        if integrity && !integrity_matches?(res.body, integrity)
+          raise RemoteFileError, uri.to_s if @options[:io_exceptions]


maybe new error that inherits from RemoteFileError ?

grosser

looks pretty good, a few nit comments/questions, otherwise 👍

JLLeitschuh and others added 2 commits September 1, 2026 14:48

grosser reviewed Sep 5, 2026

View reviewed changes

grosser approved these changes Sep 5, 2026

View reviewed changes

Navigation Menu

Uh oh!

Add Subresource Integrity (SRI) verification for remote stylesheets - #190

Add Subresource Integrity (SRI) verification for remote stylesheets#190
JLLeitschuh wants to merge 3 commits into
premailer:masterfrom
JLLeitschuh:feature/subresource-integrity

JLLeitschuh commented Sep 1, 2026 •

edited

Loading

Uh oh!

JLLeitschuh commented Sep 1, 2026

Uh oh!

JLLeitschuh commented Sep 1, 2026

Uh oh!

grosser Sep 5, 2026

Uh oh!

grosser Sep 5, 2026

Uh oh!

grosser Sep 5, 2026

Uh oh!

grosser Sep 5, 2026

Uh oh!

grosser Sep 5, 2026

Uh oh!

grosser left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

JLLeitschuh commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Testing

Uh oh!

JLLeitschuh commented Sep 1, 2026

Uh oh!

JLLeitschuh commented Sep 1, 2026

Uh oh!

grosser Sep 5, 2026

Choose a reason for hiding this comment

Uh oh!

grosser Sep 5, 2026

Choose a reason for hiding this comment

Uh oh!

grosser Sep 5, 2026

Choose a reason for hiding this comment

Uh oh!

grosser Sep 5, 2026

Choose a reason for hiding this comment

Uh oh!

grosser Sep 5, 2026

Choose a reason for hiding this comment

Uh oh!

grosser left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JLLeitschuh commented Sep 1, 2026 •

edited

Loading