Versioning and Immutability
How we version and publish the Friendly Captcha browser SDK, and how you can pin and verify the exact code that runs on your website.
This applies to both our v2 package @friendlycaptcha/sdk and our v1 package friendly-challenge. For how long v1 will be supported, see v1 and v2.
Versioning
Our browser SDK follows Semantic Versioning. In practice we have never shipped a release that wasn't backwards compatible.
Immutable Releases
We never re-release a version. Once published, the files served under a version number never change. This is also enforced by the npm registry itself, which permanently reserves a version number once it has been used.
We have never unpublished a version, and we have no plans to. Old pins should keep working indefinitely.
CDN
Version Pinning
Always reference an exact version in your script tags:
<script type="module" src="https://cdn.jsdelivr.net/npm/@friendlycaptcha/[email protected]/site.min.js" async defer></script>
<script nomodule src="https://cdn.jsdelivr.net/npm/@friendlycaptcha/[email protected]/site.compat.min.js" async defer></script>
Pinning means you decide when to upgrade, but also that you don't automatically receive fixes. We recommend that you update your pinned version periodically, with reference to the changelog.
Subresource Integrity
Subresource Integrity (SRI) pins the file's contents with an integrity hash, rather than just its URL. Because the CDN is operated by a third party, this is how you verify on every page load that the code reaching your users is the code you reviewed.
Our site scripts don't load any further JavaScript at runtime, so the two integrity hashes cover all of the JavaScript that the SDK executes on your page.
<!-- Replace both placeholder hashes using the command below. -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@friendlycaptcha/[email protected]/site.min.js" integrity="sha384-<hash of site.min.js>" crossorigin="anonymous" async defer></script>
<script nomodule src="https://cdn.jsdelivr.net/npm/@friendlycaptcha/[email protected]/site.compat.min.js" integrity="sha384-<hash of site.compat.min.js>" crossorigin="anonymous" async defer></script>
You can run this from the command-line to calculate the integrity hash for a specific file and version.
curl -sSLf https://cdn.jsdelivr.net/npm/@friendlycaptcha/[email protected]/site.min.js \
| openssl dgst -sha384 -binary | openssl base64 -A
Alternatively, there are some websites that will do this for you, like https://srihash.org/.
Self-hosting
Using cdn.jsdelivr.net is optional. You can download the release files and serve them from your own infrastructure, removing the third-party CDN from your supply chain entirely.