Skip to main content

Versioning & integrity

Introduction​

The widget URLs in these guides always serve the current release. That is the right default for most integrations — you receive fixes, including security fixes, without doing anything.

If your security review requires you to verify the code you load, or to control when it changes, read on. This page explains what is possible, what is not, and which option we recommend.

Can I use Subresource Integrity (SRI)?​

Not usefully, and we recommend against it. Two reasons.

It would verify almost none of the widget. The widget is a lazy-loading web component. auvious.esm.js is a small loader — roughly 13 KB — which at runtime imports a dozen further modules totalling around 4 MB. That is where essentially all of the widget's code lives.

Subresource Integrity only covers the file named in the <script> tag. By design it does not extend to modules that file imports. An integrity attribute on our script tag would verify about 0.3% of the code the widget executes, while appearing on your page to verify all of it.

It would break your page on our next release. The documented URL always points at the current version and is served with cache-control: no-cache. Any hash you pin stops matching the moment we publish an update, and a failed integrity check means the browser refuses to execute the script. The widget would silently disappear from your site.

caution

Do not add an integrity attribute to the unversioned widget URLs. It cannot protect what you need it to protect, and it will fail on our next deployment.

Recommended for the page itself: CSP with strict-dynamic​

If what you need is control over which scripts may run on your page, a Content Security Policy does that job properly — and unlike SRI it copes with the widget's lazy loading.

Add a nonce to the widget's script tag and use strict-dynamic:

Content-Security-Policy: script-src 'strict-dynamic' 'nonce-R4nd0m';
<script nonce="R4nd0m" type="module"
        src="https://auvious.video/widget/dist/auvious/auvious.esm.js"></script>

strict-dynamic propagates the trust you grant the root script — via its nonce — to the scripts that root loads. That is exactly the chunk-loading SRI cannot follow. It also means you no longer need to allowlist our host in script-src: when strict-dynamic is present, host allowlists in that directive are ignored.

The widget picks up your nonce automatically from either of:

<meta name="csp-nonce" content="R4nd0m" />
window.__cspNonce = "R4nd0m";

Generate a fresh nonce per response, as you would for any CSP nonce.

note

strict-dynamic governs provenance — which code is allowed to run — not integrity. It stops untrusted scripts executing on your page, which is the protection most security reviews are really asking for. It does not verify that the bytes we serve are unmodified; for that, see the npm route below. The two are complementary, not alternatives.

See Content-Security-Policy for the full set of directives the widget needs.

If you build your site with a bundler, this gives stronger guarantees than SRI ever could.

Add to your .npmrc:

@auvious:registry=https://nexus.auvious.com/repository/npm-auvious/

If you use Yarn 2 or later, it does not read .npmrc — configure the scope in .yarnrc.yml instead:

npmScopes:
  auvious:
    npmRegistryServer: "https://nexus.auvious.com/repository/npm-auvious/"

Then install:

npm install @auvious/genesys-widget

And register the components from your application entry point:

import { defineCustomElements } from "@auvious/genesys-widget/dist/loader";

defineCustomElements();

Every published version carries a SHA-512 integrity hash in the registry metadata. On install, that hash is written into your package-lock.json (or yarn.lock / pnpm-lock.yaml) and re-verified on every subsequent install and every CI build.

This covers the entire package — the loader, every lazy-loaded chunk, and the bundled assets — rather than a single entry file. Once bundled, the widget is inside your own build pipeline and covered by your existing controls.

Two things to plan for:

  • Verify the first install. Your lockfile pins whatever you fetched the first time. Confirm that version with us, then treat the lockfile as the source of truth from then on.
  • Host the runtime assets. Translations, icons and co-browse workers are fetched at runtime rather than bundled. Serve them from your own origin and point the widget at them — see setCustomAssets and assetPath.

Keeping track of new releases​

Because you control when you upgrade, you also need to know when there is something to upgrade to. Our release notes list every widget release, and the page offers RSS and Atom feeds you can subscribe to or wire into a chat channel.

Pinning a version​

warning

A pinned widget is one you must actively maintain. You stop receiving our updates automatically, including security fixes. Agree a support window and an update cadence with us before you pin, and subscribe to the release notes so you know when an update exists.

The widget talks to the Auvious backend over interfaces that evolve. We do not currently publish a compatibility window for older widget releases against the current backend, so if you intend to pin, raise it with us and we will agree one with you in writing.

Questions​

If none of the above fits your integration, contact us. Tell us what your security review needs to establish, rather than which mechanism it asked for — there is often a better answer than the one the checklist names.