@scalar/client-side-rendering 0.1.12 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @scalar/client-side-rendering
 
+## 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
+
+- [#9326](https://github.com/scalar/scalar/pull/9326): Export `DEFAULT_CDN` so consumers (e.g. `@scalar/astro`) can share the canonical fallback URL instead of duplicating it. Also widens `getConfiguration` to accept `Partial<HtmlRenderingConfiguration>`, removing the need for a `Record<string, unknown>` cast at the boundary.
+
 ## 0.1.12
 
 ## 0.1.11

package/dist/html-rendering.d.ts

@@ -1,5 +1,7 @@
 import type { AnyApiReferenceConfiguration, HtmlRenderingConfiguration } from '@scalar/types/api-reference';
 export type { AnyApiReferenceConfiguration, HtmlRenderingConfiguration };
+/** Default CDN URL for the @scalar/api-reference standalone bundle. */
+export declare const DEFAULT_CDN = "https://cdn.jsdelivr.net/npm/@scalar/api-reference";
 /**
  * Render the Scalar API Reference as a complete HTML document using the CDN.
  *
@@ -15,13 +17,28 @@ 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.
  */
-export declare const getConfiguration: (givenConfiguration: Record<string, unknown>) => Record<string, unknown>;
+export declare const getConfiguration: (givenConfiguration: Partial<HtmlRenderingConfiguration> | Record<string, unknown>) => Record<string, unknown>;
 //# sourceMappingURL=html-rendering.d.ts.map

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;AAwDxE;;;;;;;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,GAAI,oBAAoB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAcpG,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

@@ -1,10 +1,23 @@
-const DEFAULT_CDN = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference';
+/** Default CDN URL for the @scalar/api-reference standalone bundle. */
+export const DEFAULT_CDN = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference';
 /**
  * Escape HTML special characters in user-provided strings.
  */
 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
@@ -26,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 */');
@@ -40,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>`;
 };
@@ -53,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 ?? {});
@@ -62,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>
@@ -69,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>`;
 }
@@ -84,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)) {
@@ -113,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/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { type AnyApiReferenceConfiguration, type HtmlRenderingConfiguration, getConfiguration, getScriptTags, renderApiReference, } from './html-rendering.js';
+export { type AnyApiReferenceConfiguration, DEFAULT_CDN, type HtmlRenderingConfiguration, getConfiguration, getScriptTags, renderApiReference, } from './html-rendering.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,EAC/B,gBAAgB,EAChB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,4BAA4B,EACjC,WAAW,EACX,KAAK,0BAA0B,EAC/B,gBAAgB,EAChB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -1 +1 @@
-export { getConfiguration, getScriptTags, renderApiReference, } from './html-rendering.js';
+export { DEFAULT_CDN, getConfiguration, getScriptTags, renderApiReference, } from './html-rendering.js';

package/package.json

@@ -11,7 +11,7 @@
     "directory": "packages/client-side-rendering"
   },
   "keywords": [],
-  "version": "0.1.12",
+  "version": "0.2.0",
   "engines": {
     "node": ">=22"
   },
@@ -28,9 +28,9 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@scalar/schemas": "0.3.2",
-    "@scalar/validation": "0.6.0",
-    "@scalar/types": "0.12.2"
+    "@scalar/schemas": "0.4.0",
+    "@scalar/types": "0.13.0",
+    "@scalar/validation": "0.6.0"
   },
   "devDependencies": {
     "vite": "8.0.0"