jekyll-mathjax-csp 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7e8d81d890fe7c24488fd6fd9573d86504a184d0
+  data.tar.gz: 78b3d2fdf8c0065dfbbb6a47d1f3d84652e2e94f
+SHA512:
+  metadata.gz: b616058752d9bd91f13d962e0f4a0e4a6d7a8436103d44e9168cea473fffcf20d636a5367fc46313e7103bc34096ed5acb8833d96bde791ab5e8579d651b1e26
+  data.tar.gz: c92c0463764c80f2ddeac44b4b1f4e9a7c93581c13b3aa9968b1f9cc63fcce15fc9521a6563065c818f111f40ac178f8b9dd05b6f4a80814818ede6c29a15a8c

data/README.md

@@ -0,0 +1,70 @@
+# jekyll-mathjax-csp
+
+Render math on the server using [MathJax-node](https://github.com/mathjax/MathJax-node), while maintaining a strict [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) without `'unsafe-inline'`.
+
+While MathJax is well equipped to render beautiful math in a browser, letting it run in the client has two distinctive disadvantages: It is quite CPU-intensive and crucially relies on inline `style` attributes and elements. This Jekyll plugin aims to resolve both issues at once by rendering formulas to SVG images on the server, extracting all generated `style` attributes into a single `<style>` element in the head of the page and computing a hash over its content that can then be added as a CSP `style-src`.
+
+The plugin runs the output of Jekyll's markdown parser [kramdown](http://kramdown.gettalong.org/) through the CLI converter `mjpage` offered by the npm package [`mathjax-node-page`](https://github.com/pkra/mathjax-node-page) and thus behaves exactly as client-side MathJax in SVG rendering mode would.
+
+## Usage
+
+1. Install the npm package `mathjax-node-page` from your top-level Jekyll directory:
+
+   ```bash
+   npm init -f # only if you don't have a package.json yet
+   npm install mathjax-node-page@2.X
+   ```
+
+2. Install `jekyll-mathjax-csp`:
+
+   ```bash
+   gem install jekyll-mathjax-csp
+   ```
+
+3. Ensure that your `_config.yml` contains the following settings:
+
+   ```yaml
+   plugins:
+     - jekyll-mathjax-csp
+
+   exclude:
+     - node_modules
+     - package.json
+     - package-lock.json
+   ```
+
+4. Add the `{% mathjax_sources %}` Liquid tag where you want the CSP `'sha256-...'` hashes for `<style>` elements to be emitted. Don't forget to add the YAML front matter (two lines of `---`) to such files. If you specify your CSP in a different way, add the `style-src` sources the plugins prints to the console during build.
+
+5. Include beautiful math in your posts!
+
+## Dependencies
+
+* `mathjax-node-page` (npm): 2.0+
+* `html-pipeline`: 2.3+
+* `jekyll`: 3.0+
+
+## Configuration
+
+'mathjax-node-page' adds a fixed inline stylesheet to every page containing math. If you want to serve this stylesheet as an external `.css`, you can advise the plugin to strip it from the output by adding the following lines to your `_config.yml`:
+
+```yaml
+mathjax_csp:
+  strip_css: true
+```
+
+## Local testing
+
+If you want to try out your CSP locally, you can specify headers in your `_config.yml`:
+
+```yaml
+webrick:
+  headers:
+    Content-Security-Policy: >-
+      default-src 'none'; script-src ...
+```
+
+It is unfortunately not possible to have Liquid tags in `_config.yml`, so you will have to update your CSP manually. Don't forget to restart `jekyll` for it to pick up the config changes.
+
+## License
+
+MIT

data/lib/jekyll-mathjax-csp.rb

@@ -0,0 +1,217 @@
+# Server-side, CSP-aware math rendering for Jekyll using mathjax-node-page
+#
+# The MIT License (MIT)
+# =====================
+#
+# Copyright © 2018 Fabian Henneke
+#
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this software and associated documentation
+# files (the “Software”), to deal in the Software without
+# restriction, including without limitation the rights to use,
+# copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following
+# conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+require "html/pipeline"
+require "jekyll"
+
+require "digest"
+require "open3"
+require "securerandom"
+require "set"
+
+module Jekyll
+
+  # Run Jekyll documents through mathjax-node-page, transform style attributes into inline style
+  # tags and compute their hashes
+  class Mathifier
+    MATH_TAG_REGEX = /<script[^>]*type="math\/tex/i
+
+    class << self
+      attr_accessor :csp_hashes
+
+      # Extract all style attributes from SVG elements and replace them by a new CSS class with a
+      # deterministic name
+      def extractStyleAttributes(parsed_doc)
+        style_attributes = {}
+        svg_tags = parsed_doc.css("svg[style]")
+        for svg_tag in svg_tags do
+          style_attribute = svg_tag["style"]
+          digest = Digest::MD5.hexdigest(style_attribute)[0..15]
+          style_attributes[digest] = style_attribute
+
+          digest_class = "mathjax-inline-#{digest}"
+          svg_tag["class"] = "#{svg_tag["class"] || ""} #{digest_class}"
+          svg_tag.remove_attribute("style")
+        end
+        return style_attributes
+      end
+
+      # Compute a CSP hash source (using SHA256)
+      def hashStyleTag(style_tag)
+        csp_digest = "'sha256-#{Digest::SHA256.base64digest(style_tag.content)}'"
+        style_tag.add_previous_sibling("<!-- #{csp_digest} -->")
+        @csp_hashes.add(csp_digest)
+      end
+
+      # Compile all style attributes into CSS classes in a single <style> element in the head
+      def compileStyleElement(parsed_doc, style_attributes)
+        style_content = ""
+        style_attributes.each do |digest, style_attribute|
+          style_content += ".mathjax-inline-#{digest}{#{style_attribute}}"
+        end
+        style_tag = parsed_doc.at_css("head").add_child("<style>#{style_content}</style>")[0]
+        hashStyleTag(style_tag)
+      end
+
+      # Run mathjax-node-page on a String containing an HTML doc
+      def run_mjpage(output)
+        mathified = ""
+        exit_status = 0
+        begin
+          Open3.popen2("node_modules/mathjax-node-page/bin/mjpage") {|i,o,t|
+            i.print output
+            i.close
+            o.each {|line|
+              mathified.concat(line)
+            }
+            exit_status = t.value
+          }
+          return mathified unless exit_status != 0
+          Jekyll.logger.abort_with "mathjax_csp:", "'node_modules/mathjax-node-page/mjpage' not found"
+        rescue
+          Jekyll.logger.abort_with "mathjax_csp:", "Failed to execute 'node_modules/mathjax-node-page/mjpage'"
+        end
+
+      end
+
+      # Render math
+      def mathify(doc, config)
+        return unless MATH_TAG_REGEX.match?(doc.output)
+
+        Jekyll.logger.info "Rendering math:", doc.relative_path
+        parsed_doc = Nokogiri::HTML::Document.parse(doc.output)
+        # Ensure that all styles we pick up weren't present before mjpage ran
+        unless parsed_doc.css("svg[style]").empty?()
+          Jekyll.logger.error "mathjax_csp:", "Inline style on <svg> element present before running mjpage"
+          Jekyll.logger.abort_with "", "due to a misconfiguration or server-side style injection."
+        end
+
+        mjpage_output = run_mjpage(doc.output)
+        parsed_doc = Nokogiri::HTML::Document.parse(mjpage_output)
+        last_child = parsed_doc.at_css("head").last_element_child()
+        if last_child.name == "style"
+          # Set strip_css to true in _config.yml if you load the styles mjpage adds to the head
+          # from an external *.css file
+          if config["strip_css"]
+            Jekyll.logger.info "", "Remember to <link> in external stylesheet!"
+            last_child.remove
+          else
+            hashStyleTag(last_child)
+          end
+        end
+
+        style_attributes = extractStyleAttributes(parsed_doc)
+        compileStyleElement(parsed_doc, style_attributes)
+        doc.output = parsed_doc.to_html
+      end
+
+      def mathable?(doc)
+        (doc.is_a?(Jekyll::Page) || doc.write?) &&
+          doc.output_ext == ".html" || (doc.permalink && doc.permalink.end_with?("/"))
+      end
+    end
+  end
+
+  # Register the page with the {% mathjax_csp_sources %} Liquid tag for the second pass and
+  # temporarily emit a placeholder, later to be replaced by the list of MathJax-related CSP hashes
+  class MathJaxSourcesTag < Liquid::Tag
+
+    class << self
+      attr_accessor :final_source_list, :second_pass, :second_pass_docs, :unrendered_docs
+    end
+
+    def initialize(tag_name, text, tokens)
+      super
+    end
+
+    def render(context)
+      page = context.registers[:page]
+      if self.class.second_pass
+        return self.class.final_source_list
+      else
+        self.class.second_pass_docs.add(page["path"])
+        return ""
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag("mathjax_csp_sources", Jekyll::MathJaxSourcesTag)
+
+# Set up plugin config
+Jekyll::Hooks.register :site, :pre_render do |site|
+  # A set of CSP hash sources to be added as style sources; populated automatically
+  Jekyll::Mathifier.csp_hashes = Set.new([])
+  # This is the first pass (mathify & collect hashes), the second pass (insert hashes into CSP
+  # rules) is triggered manually
+  Jekyll::MathJaxSourcesTag.second_pass = false
+  # A set of Jekyll documents to which the hash sources should be added; populated automatically
+  Jekyll::MathJaxSourcesTag.second_pass_docs = Set.new([])
+  # The original file content of documents
+  Jekyll::MathJaxSourcesTag.unrendered_docs = {}
+end
+
+# Keep original (Markdown) content of documents around for the second rendering pass
+Jekyll::Hooks.register [:documents, :pages], :pre_render do |doc|
+  Jekyll::MathJaxSourcesTag.unrendered_docs[doc.relative_path] = doc.content
+end
+
+# Replace math blocks with SVG renderings using mathjax-node-page and collect inline styles in a
+# single <style> element
+Jekyll::Hooks.register [:documents, :pages], :post_render do |doc|
+  if Jekyll::Mathifier.mathable?(doc)
+    Jekyll::Mathifier.mathify(doc, doc.site.config["mathjax_csp"])
+  end
+end
+
+# Run over all documents with {% mathjax_sources %} Liquid tags again and insert the list of CSP
+# hash sources coming from MathJax styles
+Jekyll::Hooks.register :site, :post_render do |site, payload|
+  Jekyll::MathJaxSourcesTag.second_pass = true
+  Jekyll::MathJaxSourcesTag.final_source_list = Jekyll::Mathifier.csp_hashes.to_a().join(" ")
+  if Jekyll::MathJaxSourcesTag.second_pass_docs.empty?()
+    Jekyll.logger.info "mathjax_csp:", "Add the following to the style-src part of your CSP:"
+    Jekyll.logger.info "", Jekyll::MathJaxSourcesTag.final_source_list
+  else
+    second_pass_docs_str = Jekyll::MathJaxSourcesTag.second_pass_docs.to_a().join(" ")
+    Jekyll.logger.info "Adding CSP sources:", second_pass_docs_str
+    rerender = proc { |docs, uses_absolute_path|
+      docs.each do |doc|
+        relative_path = uses_absolute_path ? doc.relative_path : doc.path
+        if Jekyll::MathJaxSourcesTag.second_pass_docs.include?(relative_path)
+          # Rerender the page
+          doc.content = Jekyll::MathJaxSourcesTag.unrendered_docs[relative_path]
+          doc.output = Jekyll::Renderer.new(site, doc, payload).run()
+          doc.trigger_hooks(:post_render)
+        end
+      end
+    }
+    rerender.call(site.pages, false)
+    rerender.call(site.docs_to_write, true)
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-mathjax-csp
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Fabian Henneke
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: html-pipeline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Server-side MathJax rendering for Jekyll with a strict CSP
+email: 
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/jekyll-mathjax-csp.rb
+homepage: https://github.com/FabianHenneke/jekyll-mathjax-csp
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: Server-side MathJax & CSP for Jekyll
+test_files: []