@scalar/astro 0.3.0 → 0.4.0

package/package.json

@@ -17,7 +17,7 @@
     "openapi",
     "swagger"
   ],
-  "version": "0.3.0",
+  "version": "0.4.0",
   "engines": {
     "node": ">=22"
   },
@@ -47,7 +47,7 @@
     "documentation": "https://scalar.com/products/api-references/integrations/astro"
   },
   "dependencies": {
-    "@scalar/client-side-rendering": "0.1.13"
+    "@scalar/client-side-rendering": "0.2.0"
   },
   "devDependencies": {
     "astro": "^4.0.0 || ^5.0.0 || ^6.0.0"

package/src/ScalarClient.astro

@@ -4,13 +4,33 @@ import { getConfiguration, type HtmlRenderingConfiguration } from '@scalar/clien
 interface Props {
   config: Omit<Partial<HtmlRenderingConfiguration>, 'cdn' | 'pageTitle'>
   cdn?: string
+  /**
+   * A Content Security Policy nonce, forwarded to the client so it can stamp
+   * the dynamically injected CDN `<script>` and the `csp-nonce` meta tag that
+   * the standalone bundle reads when nonce-ing its runtime styles.
+   *
+   * Note: this does not nonce the bootstrap `<script>` below — Astro bundles
+   * and emits that tag itself, so its CSP handling is Astro's (see the comment
+   * on the script). Under a strict `script-src`, allow Astro's own scripts via
+   * its `experimental.csp` flag or `'self'`.
+   */
+  nonce?: string
 }
 
-const { config, cdn } = Astro.props
+const { config, cdn, nonce } = Astro.props
 ---
 
-<div data-scalar-client data-configuration={JSON.stringify(getConfiguration(config))} data-cdn={cdn}></div>
+<div data-scalar-client data-configuration={JSON.stringify(getConfiguration(config))} data-cdn={cdn} data-nonce={nonce}></div>
 
+{/*
+  Astro bundles this script and resolves the `./client` import, but that also
+  means Astro — not Scalar — emits the final `<script>` tag, so we cannot stamp
+  the user's `nonce` on it: adding a `nonce` attribute opts the script out of
+  bundling and leaves the import unresolved. Under a strict `script-src`, allow
+  Astro's own scripts via its `experimental.csp` flag (which nonces them) or
+  `'self'`. The nonce still reaches what Scalar controls — the CDN script and
+  the runtime styles — applied from `client.ts` via `data-nonce`.
+*/}
 <script>
   import { initScalarClient } from './client'
 

package/src/ScalarComponent.astro

@@ -32,13 +32,13 @@ const finalConfiguration = {
   ...DEFAULT_CONFIGURATION,
   ...configuration,
 }
-const { cdn, pageTitle, ...config } = finalConfiguration
+const { cdn, pageTitle, nonce, ...config } = finalConfiguration
 ---
 
 {
   renderMode === 'client' ? (
-    <ScalarClient config={config} cdn={cdn} />
+    <ScalarClient config={config} cdn={cdn} nonce={nonce} />
   ) : (
-    <div set:html={renderApiReference({ config, cdn, pageTitle })} />
+    <div set:html={renderApiReference({ config, cdn, pageTitle, nonce })} />
   )
 }

package/src/client.ts

@@ -81,10 +81,17 @@ const getState = (): ClientState => {
  * (Distinct bundles sharing one global is inherently last-one-wins; capturing
  * here keeps the common single-CDN page correct and narrows the window for the
  * rest.)
+ *
+ * The cache key also includes the nonce. A strict `script-src 'nonce-...'` only
+ * allows the `<script>` whose nonce matches the policy, so two mounts that want
+ * the same bundle under different nonces (or one with and one without) each need
+ * their own correctly-stamped tag — reusing the first load would leave the
+ * second blocked.
  */
-const loadCdn = (cdn: string): Promise<ScalarGlobal | undefined> => {
+const loadCdn = (cdn: string, nonce?: string): Promise<ScalarGlobal | undefined> => {
   const { cdnLoads } = getState()
-  const cached = cdnLoads.get(cdn)
+  const key = nonce ? `${cdn}\n${nonce}` : cdn
+  const cached = cdnLoads.get(key)
 
   if (cached) {
     return cached
@@ -93,13 +100,18 @@ const loadCdn = (cdn: string): Promise<ScalarGlobal | undefined> => {
   const load = new Promise<ScalarGlobal | undefined>((resolve, reject) => {
     const script = document.createElement('script')
     script.src = cdn
+    // Stamp the nonce so the injected bundle is allowed under a strict
+    // `script-src 'nonce-...'` policy.
+    if (nonce) {
+      script.nonce = nonce
+    }
     script.addEventListener('load', () => resolve((window as ScalarWindow).Scalar), { once: true })
     script.addEventListener(
       'error',
       () => {
         // Drop the cached failure (and the dead tag) so a later mount or
         // navigation can retry, instead of replaying this rejection forever.
-        cdnLoads.delete(cdn)
+        cdnLoads.delete(key)
         script.remove()
         reject(new Error(`[@scalar/astro] Could not load ${cdn}`))
       },
@@ -108,11 +120,34 @@ const loadCdn = (cdn: string): Promise<ScalarGlobal | undefined> => {
     document.head.appendChild(script)
   })
 
-  cdnLoads.set(cdn, load)
+  cdnLoads.set(key, load)
 
   return load
 }
 
+/**
+ * Ensure a `<meta property="csp-nonce">` is present in `<head>`.
+ *
+ * The standalone bundle reads this meta tag (it is built with `useStrictCSP`)
+ * to nonce the stylesheet it injects at runtime, so a strict `style-src` lets
+ * the bundle's `<style>` through. The static render path emits this tag in the
+ * server-rendered HTML; in client mode we add it here instead. Astro replaces
+ * `<head>` on every view transition, so this is re-checked on each mount.
+ */
+const ensureCspNonceMeta = (nonce: string): void => {
+  const existing = document.head.querySelector('meta[property="csp-nonce"]')
+
+  if (existing) {
+    existing.setAttribute('content', nonce)
+    return
+  }
+
+  const meta = document.createElement('meta')
+  meta.setAttribute('property', 'csp-nonce')
+  meta.setAttribute('content', nonce)
+  document.head.appendChild(meta)
+}
+
 /** Mount a single container, unless it is already mounted or mounting. */
 const mountContainer = (element: HTMLElement): void => {
   const state = getState()
@@ -136,12 +171,19 @@ const mountContainer = (element: HTMLElement): void => {
   }
 
   const cdn = element.dataset.cdn || DEFAULT_CDN
+  const nonce = element.dataset.nonce
   // Remember which lifecycle this mount belongs to (see `ClientState`).
   const { generation } = state
 
+  // Expose the nonce to the bundle before it loads, so the styles it injects at
+  // runtime carry the nonce too.
+  if (nonce) {
+    ensureCspNonceMeta(nonce)
+  }
+
   state.pending.add(element)
 
-  void loadCdn(cdn)
+  void loadCdn(cdn, nonce)
     .then((Scalar) => {
       // Mount only if this page is still live (no view transition happened
       // while the CDN loaded) and the element is still in the document.