Docs UI asset integrity (SRI)

The built-in /docs page renders Scalar (default) or Swagger UI by loading their JavaScript and CSS bundles from the jsDelivr CDN. A CDN keeps the framework dependency-free and means no build step for the docs UI — but it also means the browser will execute whatever bytes the CDN serves. If a CDN asset were ever poisoned, that code would run in the context of your docs page.

As of 0.37.0, the docs helpers accept Subresource Integrity (SRI) hashes. When you pin one, DaloyJS emits an integrity="…" attribute plus a crossorigin attribute on the matching <script> / <link>tag, so the browser refuses to execute an asset whose bytes don't match the pinned hash — the docs UI inherits the same supply-chain posture as the rest of the framework.

Why it's opt-in

SRI only works against a version-pinned, byte-stable URL. The framework's default asset URLs intentionally track the latest upstream release (so you get fixes without bumping DaloyJS), which means they cannot carry a fixed hash — the bytes change whenever Scalar or Swagger UI publishes. To pin SRI you therefore supply both a version-exact URL and its matching hash.

Pin SRI on the auto-mounted docs

import { App } from "@daloyjs/core";

const app = new App({
  docs: {
    assets: {
      // Pin the exact version you verified...
      scalarScriptUrl:
        "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.0",
      // ...and the SRI hash of that exact file.
      scalarScriptIntegrity: "sha384-<base64-digest>",
    },
  },
});

The same assets object works for the Swagger UI renderer, which loads two assets (a stylesheet and a bundle):

const app = new App({
  docs: {
    ui: "swagger",
    assets: {
      swaggerUiCssUrl:
        "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14/swagger-ui.css",
      swaggerUiCssIntegrity: "sha384-<css-digest>",
      swaggerUiBundleUrl:
        "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14/swagger-ui-bundle.js",
      swaggerUiBundleIntegrity: "sha384-<bundle-digest>",
    },
  },
});

Computing the hash

Download the exact pinned file and hash it. The output is exactly what goes into the *Integrity field:

curl -sSL https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.0 \
  | openssl dgst -sha384 -binary \
  | openssl base64 -A \
  | sed 's/^/sha384-/'

jsDelivr also surfaces a copy-paste SRI snippet on each file's page, which is a convenient cross-check. Re-run this whenever you bump the pinned version.

Self-hosting instead

If your Content-Security-Policy forbids third-party CDNs, point the same assets URLs at copies you serve yourself. SRI is optional in that case (the assets are same-origin and under your control), but you can still pin hashes for defense in depth.

const app = new App({
  docs: {
    assets: {
      scalarScriptUrl: "/docs-assets/scalar.js",
    },
  },
});

Malformed hashes fail loudly

A typo in an SRI value is dangerous: browsers silently ignore an unparseable integrityattribute and load the asset anyway, giving you a false sense of protection. To prevent that, DaloyJS validates every hash up front. A value that isn't one or more space-separated sha256- / sha384- / sha512- base64 digests throws a TypeError at startup rather than shipping an unprotected page.

// Throws: Invalid Subresource Integrity value: "md5-nope". ...
new App({
  docs: {
    assets: {
      scalarScriptUrl:
        "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.0",
      scalarScriptIntegrity: "md5-nope",
    },
  },
});

Low-level helpers

The same options flow through the scalarHtml() and swaggerUiHtml() helpers (from the @daloyjs/core/docs subpath) if you render the docs page yourself. Multiple digests are supported — separate them with whitespace, and the strongest one the browser understands wins. The crossOrigin field defaults to "anonymous"; set it to "use-credentials" only when the asset host needs credentialed requests.

import { scalarHtml } from "@daloyjs/core/docs";

const html = scalarHtml({
  specUrl: "/openapi.json",
  assets: {
    scalarScriptUrl:
      "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.0",
    scalarScriptIntegrity:
      "sha384-<primary> sha512-<fallback>",
    crossOrigin: "anonymous",
  },
});

Search docs