@scalar/client-side-rendering 0.1.13 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @scalar/client-side-rendering
 
+## 0.2.1
+
+## 0.2.0
+
+### Minor Changes
+
+- [#9422](https://github.com/scalar/scalar/pull/9422): Add a `nonce` option for Content Security Policy support.
+
+  When you pass a `nonce`, the rendered HTML stamps it onto the inline `<script>` and the CDN `<script>` tag (and Scalar's own `<style>` tags, plus a matching `<meta property="csp-nonce">`). This lets the API Reference run under a strict `script-src` with no `unsafe-inline` and no `unsafe-eval`.
+
+  ```ts
+  ApiReference({
+    url: '/openapi.json',
+    // Match this value in your `script-src` CSP directive.
+    nonce: 'r4nd0m',
+  })
+  ```
+
+  Note: `style-src` still needs `'unsafe-inline'`. The reference renders inline `style="…"` attributes, which a CSP nonce can never authorize (nonces only apply to `<script>`, `<style>` and `<link>` elements), so a nonce-only `style-src` is not possible. The win is a fully strict `script-src`.
+
 ## 0.1.13
 
 ### Patch Changes

package/dist/html-rendering.d.ts

@@ -17,11 +17,26 @@ export declare function renderApiReference(options: {
     pageTitle?: string;
     /** CDN URL for the standalone bundle. Defaults to jsDelivr. */
     cdn?: string;
+    /**
+     * A Content Security Policy (CSP) nonce to apply to the generated inline `<script>` and `<style>`
+     * tags (and the CDN `<script>` tag).
+     *
+     * When set, a `<meta property="csp-nonce">` tag is also emitted so the standalone bundle can apply
+     * the same nonce to the stylesheet it injects at runtime. This lets the API Reference run under a
+     * strict `script-src` with no `unsafe-inline` and no `unsafe-eval`.
+     *
+     * Note: `style-src` still needs `'unsafe-inline'`, because the reference renders inline
+     * `style="..."` attributes that a CSP nonce cannot authorize.
+     */
+    nonce?: string;
 }, customTheme?: string): string;
 /**
  * The script tags to load the @scalar/api-reference package from the CDN.
+ *
+ * When a `nonce` is provided it is applied to both script tags so they are allowed under a strict
+ * `script-src` Content Security Policy.
  */
-export declare function getScriptTags(configuration: Record<string, unknown>, cdn?: string): string;
+export declare function getScriptTags(configuration: Record<string, unknown>, cdn?: string, nonce?: string): string;
 /**
  * The configuration to pass to the @scalar/api-reference package.
  */

package/dist/html-rendering.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html-rendering.d.ts","sourceRoot":"","sources":["../src/html-rendering.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAE3G,YAAY,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,CAAA;AAExE,uEAAuE;AACvE,eAAO,MAAM,WAAW,uDAAuD,CAAA;AAsD/E;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE;IACP,uCAAuC;IACvC,MAAM,EAAE,4BAA4B,CAAA;IACpC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,EACD,WAAW,SAAK,GACf,MAAM,CA0BR;AASD;;GAEG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAwC1F;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,oBAAoB,OAAO,CAAC,0BAA0B,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChF,MAAM,CAAC,MAAM,EAAE,OAAO,CAcxB,CAAA"}
+{"version":3,"file":"html-rendering.d.ts","sourceRoot":"","sources":["../src/html-rendering.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAE3G,YAAY,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,CAAA;AAExE,uEAAuE;AACvE,eAAO,MAAM,WAAW,uDAAuD,CAAA;AAoE/E;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE;IACP,uCAAuC;IACvC,MAAM,EAAE,4BAA4B,CAAA;IACpC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,EACD,WAAW,SAAK,GACf,MAAM,CA8BR;AASD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CA0C1G;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,oBAAoB,OAAO,CAAC,0BAA0B,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChF,MAAM,CAAC,MAAM,EAAE,OAAO,CAcxB,CAAA"}

package/dist/html-rendering.js

@@ -6,6 +6,18 @@ export const DEFAULT_CDN = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference';
 const escapeHtml = (str) => {
     return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 };
+/**
+ * Escape a value for use inside a double-quoted HTML attribute.
+ *
+ * On top of the regular HTML escaping we also encode double quotes so the value cannot break out of
+ * the attribute. Used for the CSP nonce, which is attacker-influenced in some setups.
+ */
+const escapeHtmlAttribute = (str) => escapeHtml(str).replace(/"/g, '&quot;');
+/**
+ * Build a ` nonce="..."` attribute (with a leading space) when a nonce is provided, otherwise an
+ * empty string. Returned ready to be interpolated into a tag.
+ */
+const nonceAttribute = (nonce) => (nonce ? ` nonce="${escapeHtmlAttribute(nonce)}"` : '');
 /**
  * Helper function to add consistent indentation to multiline strings
  * @param str The string to indent
@@ -27,7 +39,7 @@ const addIndent = (str, spaces = 2, initialIndent = false) => {
 /**
  * Generate the style tag with custom theme if needed
  */
-const getStyles = (configuration, customTheme) => {
+const getStyles = (configuration, customTheme, nonce) => {
     const styles = [];
     if (configuration.customCss) {
         styles.push('/* Custom CSS */');
@@ -41,7 +53,7 @@ const getStyles = (configuration, customTheme) => {
         return '';
     }
     return `
-    <style type="text/css">
+    <style type="text/css"${nonceAttribute(nonce)}>
       ${addIndent(styles.join('\n\n'), 6)}
     </style>`;
 };
@@ -54,7 +66,7 @@ const getStyles = (configuration, customTheme) => {
  * For server-side rendering with hydration, use the server module instead.
  */
 export function renderApiReference(options, customTheme = '') {
-    const { config: givenConfig, pageTitle, cdn } = options;
+    const { config: givenConfig, pageTitle, cdn, nonce } = options;
     const title = escapeHtml(pageTitle ?? 'Scalar API Reference');
     const unwrapped = Array.isArray(givenConfig) ? givenConfig[0] : givenConfig;
     const { customCss, theme, ...rest } = (unwrapped ?? {});
@@ -63,6 +75,9 @@ export function renderApiReference(options, customTheme = '') {
         ...(theme ? { theme } : {}),
         ...(customCss !== undefined ? { customCss } : {}),
     });
+    // Expose the nonce to the standalone bundle so it can apply it to the stylesheet it injects at
+    // runtime (the bundle reads `meta[property=csp-nonce]` when built with `useStrictCSP`).
+    const cspNonceMeta = nonce ? `\n    <meta property="csp-nonce" content="${escapeHtmlAttribute(nonce)}" />` : '';
     return `<!doctype html>
 <html>
   <head>
@@ -70,10 +85,10 @@ export function renderApiReference(options, customTheme = '') {
     <meta charset="utf-8" />
     <meta
       name="viewport"
-      content="width=device-width, initial-scale=1" />${getStyles(configuration, customTheme)}
+      content="width=device-width, initial-scale=1" />${cspNonceMeta}${getStyles(configuration, customTheme, nonce)}
   </head>
   <body>
-    <div id="app"></div>${getScriptTags(configuration, cdn)}
+    <div id="app"></div>${getScriptTags(configuration, cdn, nonce)}
   </body>
 </html>`;
 }
@@ -85,8 +100,11 @@ const serializeArrayWithFunctions = (arr) => {
 };
 /**
  * The script tags to load the @scalar/api-reference package from the CDN.
+ *
+ * When a `nonce` is provided it is applied to both script tags so they are allowed under a strict
+ * `script-src` Content Security Policy.
  */
-export function getScriptTags(configuration, cdn) {
+export function getScriptTags(configuration, cdn, nonce) {
     const restConfig = { ...configuration };
     const functionProps = [];
     for (const [key, value] of Object.entries(configuration)) {
@@ -114,12 +132,13 @@ export function getScriptTags(configuration, cdn) {
             configString = `${jsonWithoutClosingBrace},\n        ${functionProps.join(',\n        ')}\n      }`;
         }
     }
+    const nonceAttr = nonceAttribute(nonce);
     return `
     <!-- Load the Script -->
-    <script src="${cdn ?? DEFAULT_CDN}"></script>
+    <script src="${cdn ?? DEFAULT_CDN}"${nonceAttr}></script>
 
     <!-- Initialize the Scalar API Reference -->
-    <script type="text/javascript">
+    <script type="text/javascript"${nonceAttr}>
       Scalar.createApiReference('#app', ${configString})
     </script>`;
 }

package/package.json

@@ -11,7 +11,7 @@
     "directory": "packages/client-side-rendering"
   },
   "keywords": [],
-  "version": "0.1.13",
+  "version": "0.2.1",
   "engines": {
     "node": ">=22"
   },
@@ -28,8 +28,8 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@scalar/schemas": "0.3.3",
-    "@scalar/types": "0.12.3",
+    "@scalar/schemas": "0.4.1",
+    "@scalar/types": "0.13.1",
     "@scalar/validation": "0.6.0"
   },
   "devDependencies": {
@@ -38,6 +38,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "test": "vitest --run",
-    "types:check": "tsc --noEmit"
+    "types:check": "tsgo --noEmit"
   }
 }