Pin library versions with integrity hashes, and update them each June

Open
#3,321 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
python, xml
Domain
build-system

Research direction

Start by reviewing the listed CDN references in xsl/pretext-html.xsl, xsl/pretext-revealjs.xsl, xsl/publisher-variables.xsl, and xsl/extract-runestone-page-template.xsl, along with Python version checks in pretext/README.md and pretext/lib/pretext.py. First resolve the MathJax and Python support policy decisions, then inventory each listed library and its current version and hash. Done means versions and integrity attributes are updated and tested, and the yearly decisions and Python history are recorded.

Written by the indexing model from the issue text.

Description

HTML output loads a number of third-party libraries from content delivery networks (CDNs). Good practice is to load an exact version of each, with a Subresource Integrity hash (the integrity attribute), so that a browser refuses any file other than the one that was tested. An exact version changes only when we change it, so changes can be planned. The plan is one update a year, in early June, when the academic year has ended in the Northern hemisphere and before the next one begins, so that no version changes under a class in session. The first is June 2027.

JSXGraph comes early, in December 2026: PR #3291 updates the library for interactive/@platform="jsxgraph", and the deprecated jsxgraph element, with its own older copy of the library, loses its support at the same time.

Libraries loaded at a version that moves

  • MathJax: mathjax@4 in xsl/pretext-html.xsl, and mathjax@4/tex-mml-chtml.js for reveal.js slideshows in xsl/pretext-revealjs.xsl. See the decision below.
  • reveal.js: reveal.js@6/dist, the default address in xsl/publisher-variables.xsl for a publication file whose resources are on a CDN or embedded.
  • Mermaid: mermaid@11, and its ELK layout package @mermaid-js/layout-elk with no version at all, in xsl/pretext-html.xsl.
  • DoenetML: @doenet/standalone@latest, unless docinfo/doenetml/@version or an interactive/@version names a version.
  • D3: d3js.org/d3.v5.min.js, the newest release of version 5, with interactive/@version choosing 3, 4, or 5.
  • PreTeXt's own CSS and JavaScript, for builds that take them from a CDN: html-static@latest, unless the CLI supplies its own version.

Exact versions without an integrity hash

  • Prism 1.26.0: the core, the autoloader, and prism.css. Its line-numbers and line-highlight plugins, with their CSS, already carry hashes.
  • JSXGraph: 1.8.0, for interactive/@platform="jsxgraph", and 0.99.6, for the deprecated jsxgraph element; both are handled in December, as above.
  • Font Awesome 5.15.4: the CSS from use.fontawesome.com.
  • Bootstrap 4.5.3: in the Runestone page template, xsl/extract-runestone-page-template.xsl. Popper 1.16.1, loaded beside it, already carries a hash.

Already exact and hashed: lunr 2.3.9, the two Prism plugins, Popper 1.16.1.

Scripts with no version to choose

These are served by a service for its own interface, and change when the service changes, so a hash would break at the service's next update. They are listed so that the yearly update knows of them: GeoGebra deployggb.js, SageCell embedded_sagecell.js and its CSS, Hypothesis embed.js, the WeBWorK server's iframeResizer.min.js, Google custom search, Google Analytics and gtag, StatCounter, and Ethical Ads in books hosted on Runestone.

Fonts are similar: Google Fonts (several families, and Material Symbols) sends different CSS to different browsers, so it cannot carry a hash; DejaVu Serif comes from fonts.cdnfonts.com.

A decision: should MathJax keep a moving version?

mathjax@4 brings every 4.x release, with its fixes, without any change here. A hash fixes the exact bytes of one file, so a hash means an exact version, and then MathJax is updated by hand, once a year, like everything else. Either way, MathJax loads its own components (input, output, fonts, accessibility) from the same address, and those carry no hash; an exact version is what keeps them fixed. Prism's autoloader and Mermaid's module files work the same way.

Python

The package expects Python 3.10 or newer (pretext/README.md, and the check at startup in pretext/lib/pretext.py), and the CLI's requires-python is >=3.10. Python 3.10 reached its end of life in October 2026, and 3.11 reaches its end of life in October 2027. The yearly update is a good time to decide the oldest version for the coming year, in step with the CLI. The history at the top of pretext/lib/pretext.py records each change, and vermin reports what the code requires.

Each June

  • Move each exact version to its current release, test, and record a new hash, for example from openssl dgst -sha384 -binary <file> | openssl base64 -A, written as sha384-<value>. A file with a hash, served from another site, also needs crossorigin="anonymous".
  • Decide again, for each library above with a moving version, whether it stays that way.
  • Decide the oldest supported Python.

Claude Opus 5.5, acting as a coding assistant for Rob Beezer

Dominant language
XSLT
Stars
466
Forks
251
Avg merge
4m
Merged PRs (30d)
13

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from PreTeXtBook/pretext

All issues in PreTeXtBook/pretext

Similar issues

More Build System issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.