From 719f8b8daf203970f48be3b1777fa24a22f7ff94 Mon Sep 17 00:00:00 2001
From: Jeff Johnson <jeff.johnson@gusto.com>
Date: Wed, 17 Jun 2026 11:42:52 -0700
Subject: [PATCH 1/3] feat: add CSP nonce support to GustoProvider
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an optional `nonce` prop to `GustoProvider` and
`GustoProviderCustomUIAdapter` so partners with a strict
`style-src 'nonce-…'` Content Security Policy can run the SDK without
relaxing to `unsafe-inline`. The nonce is applied to both runtime
`<style>` injection sites (the ThemeProvider variables element and the
paystub PDF download window's loading-spinner element), and exposed to
custom UI components via a new `useNonce` hook.

Also extracts three static inline `style={{…}}` attributes (Card,
Toast, DocumentSigner List) to CSS modules so they no longer require
`style-src-attr 'unsafe-inline'`. The remaining inline-style surface
(`Flex`/`Grid`/`ProgressBar`/`ReorderableList` runtime CSS custom
properties, plus `react-aria-components` overlay positioning) is
documented in the partner CSP guide.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../proxy-security-partner-guidance.md        | 58 +++++++++++++++++++
 src/components/Common/Toast/Toast.module.scss |  4 ++
 src/components/Common/Toast/Toast.tsx         |  3 +-
 .../Common/UI/Card/Card.module.scss           |  5 ++
 src/components/Common/UI/Card/Card.tsx        |  2 +-
 .../DocumentList/List.module.scss             |  3 +
 .../DocumentSigner/DocumentList/List.tsx      |  3 +-
 .../PaystubsCard/PaystubsCard.test.tsx        | 48 +++++++++++++++
 .../management/PaystubsCard/PaystubsCard.tsx  |  5 +-
 .../GustoProviderCustomUIAdapter.tsx          | 54 ++++++++++-------
 src/contexts/NonceProvider/index.ts           |  1 +
 src/contexts/NonceProvider/useNonce.test.tsx  | 19 ++++++
 src/contexts/NonceProvider/useNonce.ts        | 40 +++++++++++++
 .../ThemeProvider/ThemeProvider.test.tsx      | 31 ++++++++++
 src/contexts/ThemeProvider/ThemeProvider.tsx  |  5 +-
 src/contexts/index.ts                         |  1 +
 16 files changed, 255 insertions(+), 27 deletions(-)
 create mode 100644 src/components/Common/Toast/Toast.module.scss
 create mode 100644 src/components/Employee/Documents/onboarding/DocumentSigner/DocumentList/List.module.scss
 create mode 100644 src/contexts/NonceProvider/index.ts
 create mode 100644 src/contexts/NonceProvider/useNonce.test.tsx
 create mode 100644 src/contexts/NonceProvider/useNonce.ts

diff --git a/docs/getting-started/proxy-security-partner-guidance.md b/docs/getting-started/proxy-security-partner-guidance.md
index 201fdfd61..627583cda 100644
--- a/docs/getting-started/proxy-security-partner-guidance.md
+++ b/docs/getting-started/proxy-security-partner-guidance.md
@@ -68,6 +68,64 @@ Look up the flows or blocks your app uses, substitute `:param` placeholders with
 
 See the [endpoint reference tables](../reference/endpoint-reference.md) for a human-readable list. Copy the method + path pairs for the components you use and substitute `:param` placeholders with session values at runtime.
 
+## Content Security Policy
+
+The SDK ships a static stylesheet at `@gusto/embedded-react-sdk/style.css` and injects two runtime `<style>` elements at the browser: one for active theme variables, and one inside the new window opened during a paystub PDF download. Both accept a CSP nonce.
+
+### Passing a nonce
+
+Pass the same per-request nonce your app uses for `style-src 'nonce-…'` to `GustoProvider`. The SDK applies it to every `<style>` element it creates.
+
+```tsx
+import { GustoProvider } from '@gusto/embedded-react-sdk'
+
+function App({ cspNonce }: { cspNonce: string }) {
+  return (
+    <GustoProvider config={{ baseUrl: '/proxy/' }} nonce={cspNonce}>
+      …
+    </GustoProvider>
+  )
+}
+```
+
+The same prop is available on `GustoProviderCustomUIAdapter`. If a custom UI component you supply injects its own runtime `<style>` or `<script>`, read the nonce with `useNonce`:
+
+```tsx
+import { useEffect } from 'react'
+import { useNonce } from '@gusto/embedded-react-sdk'
+
+function InjectedStyles({ css }: { css: string }) {
+  const nonce = useNonce()
+  useEffect(() => {
+    const el = document.createElement('style')
+    if (nonce) el.nonce = nonce
+    el.textContent = css
+    document.head.appendChild(el)
+    return () => {
+      el.remove()
+    }
+  }, [css, nonce])
+  return null
+}
+```
+
+`useNonce` returns `undefined` when no nonce was supplied.
+
+### Minimum policy
+
+```
+Content-Security-Policy:
+  style-src 'self' 'nonce-XYZ';
+  style-src-attr 'unsafe-inline';
+  script-src 'self' 'nonce-XYZ';
+  img-src 'self' data:;
+```
+
+- `style-src 'self' 'nonce-XYZ'` covers the bundled stylesheet and the two runtime `<style>` elements once the nonce is wired through `GustoProvider`.
+- `style-src-attr 'unsafe-inline'` is required by inline `style="…"` attributes the SDK uses to apply runtime-computed CSS custom properties (responsive flex and grid layouts, progress-bar fill width, animation timings) and by `react-aria-components` for overlay positioning. The CSP specification does not allow per-attribute nonces, so this directive cannot be tightened further without dropping these features upstream.
+- `script-src 'self' 'nonce-XYZ'` — the SDK does not use `eval` or inject `<script>` elements. The nonce is for your own scripts.
+- `img-src 'self' data:` is only required if your integration uploads images. The SDK converts uploaded files to `data:` URLs before submitting them.
+
 ## FAQ
 
 **Can an authenticated employee access another employee's data?**
diff --git a/src/components/Common/Toast/Toast.module.scss b/src/components/Common/Toast/Toast.module.scss
new file mode 100644
index 000000000..eb49e2174
--- /dev/null
+++ b/src/components/Common/Toast/Toast.module.scss
@@ -0,0 +1,4 @@
+.toast {
+  background-color: rgba(255, 0, 0, 0.2);
+  color: red;
+}
diff --git a/src/components/Common/Toast/Toast.tsx b/src/components/Common/Toast/Toast.tsx
index b49b48010..717ef547e 100644
--- a/src/components/Common/Toast/Toast.tsx
+++ b/src/components/Common/Toast/Toast.tsx
@@ -1,3 +1,4 @@
+import styles from './Toast.module.scss'
 import { useComponentContext } from '@/contexts/ComponentAdapter/useComponentContext'
 //TODO: Style appropriately once design is available
 /** @internal */
@@ -5,7 +6,7 @@ export function Toast({ message, onClose }: { message: string | null; onClose: (
   const Components = useComponentContext()
   if (!message) return
   return (
-    <div role="alert" style={{ backgroundColor: 'rgba(255,0,0,0.2)', color: 'red' }}>
+    <div role="alert" className={styles.toast}>
       {message}
       <Components.Button onClick={onClose}>Close</Components.Button>
     </div>
diff --git a/src/components/Common/UI/Card/Card.module.scss b/src/components/Common/UI/Card/Card.module.scss
index 64dd78d26..565c0cbb1 100644
--- a/src/components/Common/UI/Card/Card.module.scss
+++ b/src/components/Common/UI/Card/Card.module.scss
@@ -6,3 +6,8 @@
   background-color: var(--g-colorBody);
   box-shadow: var(--g-shadowResting);
 }
+
+.cardBody {
+  flex-grow: 1;
+  flex-shrink: 1;
+}
diff --git a/src/components/Common/UI/Card/Card.tsx b/src/components/Common/UI/Card/Card.tsx
index 4668acba6..f6e4a9953 100644
--- a/src/components/Common/UI/Card/Card.tsx
+++ b/src/components/Common/UI/Card/Card.tsx
@@ -15,7 +15,7 @@ export function Card({ children, menu, className, action }: CardProps) {
     <div className={cn(styles.cardContainer, className)} data-testid="data-card">
       <Flex flexDirection="row" gap={8}>
         {action && <div>{action}</div>}
-        <div style={{ flexGrow: 1, flexShrink: 1 }}>
+        <div className={styles.cardBody}>
           <Flex flexDirection={'column'} gap={16}>
             {children}
           </Flex>
diff --git a/src/components/Employee/Documents/onboarding/DocumentSigner/DocumentList/List.module.scss b/src/components/Employee/Documents/onboarding/DocumentSigner/DocumentList/List.module.scss
new file mode 100644
index 000000000..88de80d08
--- /dev/null
+++ b/src/components/Employee/Documents/onboarding/DocumentSigner/DocumentList/List.module.scss
@@ -0,0 +1,3 @@
+.root {
+  width: 100%;
+}
diff --git a/src/components/Employee/Documents/onboarding/DocumentSigner/DocumentList/List.tsx b/src/components/Employee/Documents/onboarding/DocumentSigner/DocumentList/List.tsx
index 12b8b39fd..dd2afceb0 100644
--- a/src/components/Employee/Documents/onboarding/DocumentSigner/DocumentList/List.tsx
+++ b/src/components/Employee/Documents/onboarding/DocumentSigner/DocumentList/List.tsx
@@ -1,5 +1,6 @@
 import { useTranslation } from 'react-i18next'
 import { useDocumentList } from './useDocumentList'
+import styles from './List.module.scss'
 import { Flex, DocumentList as SharedDocumentList } from '@/components/Common'
 
 /** @internal */
@@ -8,7 +9,7 @@ export function List() {
   const { t } = useTranslation('Employee.DocumentSigner')
 
   return (
-    <section style={{ width: '100%' }}>
+    <section className={styles.root}>
       <Flex flexDirection="column" gap={32}>
         <SharedDocumentList
           forms={employeeForms.map(form => ({
diff --git a/src/components/Employee/Paystubs/management/PaystubsCard/PaystubsCard.test.tsx b/src/components/Employee/Paystubs/management/PaystubsCard/PaystubsCard.test.tsx
index 7f8d938b6..bbe22e142 100644
--- a/src/components/Employee/Paystubs/management/PaystubsCard/PaystubsCard.test.tsx
+++ b/src/components/Employee/Paystubs/management/PaystubsCard/PaystubsCard.test.tsx
@@ -8,6 +8,7 @@ import { setupApiTestMocks } from '@/test/mocks/apiServer'
 import { server } from '@/test/mocks/server'
 import { API_BASE_URL } from '@/test/constants'
 import { componentEvents } from '@/shared/constants'
+import { NonceContext } from '@/contexts/NonceProvider'
 
 const stubPayStubs = (
   payStubs: Array<Record<string, unknown>>,
@@ -131,4 +132,51 @@ describe('PaystubsCard', () => {
       revokeObjectURLSpy.mockRestore()
     }
   })
+
+  it('applies the CSP nonce from NonceContext to the popup style element', async () => {
+    stubPayStubs(TWO_STUBS, { 'x-total-count': '2', 'x-total-pages': '1', 'x-page': '1' })
+    server.use(
+      http.get(`${API_BASE_URL}/v1/payrolls/:payroll_id/employees/:employee_id/pay_stub`, () =>
+        HttpResponse.json({ document_url: 'http://example.com/paystub.pdf' }),
+      ),
+    )
+
+    const popupDoc = document.implementation.createHTMLDocument('popup')
+    const popupWindow = {
+      document: popupDoc,
+      addEventListener: vi.fn(),
+      close: vi.fn(),
+      location: { href: '' },
+    } as unknown as Window
+    const openSpy = vi.spyOn(window, 'open').mockReturnValue(popupWindow)
+    const createObjectURLSpy = vi
+      .spyOn(URL, 'createObjectURL')
+      .mockReturnValue('blob:mock-blob-url')
+    const revokeObjectURLSpy = vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {})
+
+    try {
+      const user = userEvent.setup()
+      renderWithProviders(
+        <NonceContext.Provider value="csp-test-nonce">
+          <PaystubsCard employeeId="employee-123" onEvent={vi.fn()} />
+        </NonceContext.Provider>,
+      )
+
+      await waitFor(() => {
+        expect(screen.getAllByRole('button', { name: 'Download paystub' })).toHaveLength(2)
+      })
+
+      const [firstDownload] = screen.getAllByRole('button', { name: 'Download paystub' })
+      await user.click(firstDownload!)
+
+      await waitFor(() => {
+        const popupStyle = popupDoc.head.querySelector<HTMLStyleElement>('style')
+        expect(popupStyle?.nonce).toBe('csp-test-nonce')
+      })
+    } finally {
+      openSpy.mockRestore()
+      createObjectURLSpy.mockRestore()
+      revokeObjectURLSpy.mockRestore()
+    }
+  })
 })
diff --git a/src/components/Employee/Paystubs/management/PaystubsCard/PaystubsCard.tsx b/src/components/Employee/Paystubs/management/PaystubsCard/PaystubsCard.tsx
index f46b68f83..0a3318160 100644
--- a/src/components/Employee/Paystubs/management/PaystubsCard/PaystubsCard.tsx
+++ b/src/components/Employee/Paystubs/management/PaystubsCard/PaystubsCard.tsx
@@ -9,6 +9,7 @@ import {
 import { DataView, EmptyData, useDataView, Loading } from '@/components/Common'
 import { BaseBoundaries, BaseLayout } from '@/components/Base/Base'
 import { useComponentContext } from '@/contexts/ComponentAdapter/useComponentContext'
+import { useNonce } from '@/contexts/NonceProvider'
 import { composeErrorHandler } from '@/partner-hook-utils/composeErrorHandler'
 import {
   usePaymentMethodList,
@@ -99,6 +100,7 @@ function PaystubsCardReady({
   const Components = useComponentContext()
   const formatCurrency = useNumberFormatter('currency')
   const { showBoundary } = useErrorBoundary()
+  const nonce = useNonce()
 
   const [downloadingPayrollUuids, setDownloadingPayrollUuids] = useState<ReadonlySet<string>>(
     () => new Set(),
@@ -127,6 +129,7 @@ function PaystubsCardReady({
         const doc = newWindow.document
         doc.title = loadingMessage
         const style = doc.createElement('style')
+        if (nonce) style.nonce = nonce
         style.textContent =
           'body{font-family:system-ui,-apple-system,sans-serif;display:flex;align-items:center;' +
           'justify-content:center;height:100vh;margin:0;color:#444;gap:12px}' +
@@ -179,7 +182,7 @@ function PaystubsCardReady({
         })
       }
     },
-    [paystubsList.actions, onEvent, employeeId, t, showBoundary],
+    [paystubsList.actions, onEvent, employeeId, t, showBoundary, nonce],
   )
 
   const payStubsColumns = [
diff --git a/src/contexts/GustoProvider/GustoProviderCustomUIAdapter.tsx b/src/contexts/GustoProvider/GustoProviderCustomUIAdapter.tsx
index 46920ded4..23be8df23 100644
--- a/src/contexts/GustoProvider/GustoProviderCustomUIAdapter.tsx
+++ b/src/contexts/GustoProvider/GustoProviderCustomUIAdapter.tsx
@@ -14,6 +14,7 @@ import { sanitizeError } from '../ObservabilityProvider/sanitization'
 import { SDKI18next } from './SDKI18next'
 import { InternalError } from '@/components/Common'
 import { LocaleProvider } from '@/contexts/LocaleProvider'
+import { NonceContext } from '@/contexts/NonceProvider'
 import { ThemeProvider } from '@/contexts/ThemeProvider'
 import type { GustoSDKTheme } from '@/contexts/ThemeProvider/theme'
 import type { ResourceDictionary, SupportedLanguages } from '@/types/Helpers'
@@ -55,6 +56,12 @@ export interface GustoProviderProps {
   currency?: string
   /** Theme overrides applied to SDK components. See {@link GustoSDKTheme}. */
   theme?: Partial<GustoSDKTheme>
+  /**
+   * CSP nonce to apply to runtime-injected `<style>` elements (theming, PDF download window).
+   * Pass the same per-request nonce your app uses in its `style-src 'nonce-…'` directive.
+   * Also exposed to custom UI components via `useNonce`.
+   */
+  nonce?: string
   /** Element to use as the portal container for SDK popovers and dropdowns. Useful when rendering inside a modal or shadow root. */
   portalContainer?: HTMLElement
   /** Optional TanStack Query `QueryClient`. When omitted, the SDK creates its own client configured for Gusto's API. */
@@ -97,6 +104,7 @@ const GustoProviderCustomUIAdapter: React.FC<GustoProviderCustomUIAdapterProps>
     locale = 'en-US',
     currency = 'USD',
     theme,
+    nonce,
     portalContainer,
     components,
     LoaderComponent,
@@ -144,28 +152,30 @@ const GustoProviderCustomUIAdapter: React.FC<GustoProviderCustomUIAdapterProps>
     }
   }, [config.observability])
   return (
-    <ComponentsProvider value={components}>
-      <LoadingIndicatorProvider value={LoaderComponent}>
-        <ObservabilityProvider observability={config.observability}>
-          <ErrorBoundary FallbackComponent={InternalError} onError={handleTopLevelError}>
-            <ThemeProvider theme={theme} portalContainer={portalContainer}>
-              <LocaleProvider locale={locale} currency={currency}>
-                <I18nextProvider i18n={SDKI18next} key={lng}>
-                  <ApiProvider
-                    url={config.baseUrl}
-                    headers={config.headers}
-                    hooks={config.hooks}
-                    queryClient={queryClient}
-                  >
-                    {children}
-                  </ApiProvider>
-                </I18nextProvider>
-              </LocaleProvider>
-            </ThemeProvider>
-          </ErrorBoundary>
-        </ObservabilityProvider>
-      </LoadingIndicatorProvider>
-    </ComponentsProvider>
+    <NonceContext.Provider value={nonce}>
+      <ComponentsProvider value={components}>
+        <LoadingIndicatorProvider value={LoaderComponent}>
+          <ObservabilityProvider observability={config.observability}>
+            <ErrorBoundary FallbackComponent={InternalError} onError={handleTopLevelError}>
+              <ThemeProvider theme={theme} portalContainer={portalContainer}>
+                <LocaleProvider locale={locale} currency={currency}>
+                  <I18nextProvider i18n={SDKI18next} key={lng}>
+                    <ApiProvider
+                      url={config.baseUrl}
+                      headers={config.headers}
+                      hooks={config.hooks}
+                      queryClient={queryClient}
+                    >
+                      {children}
+                    </ApiProvider>
+                  </I18nextProvider>
+                </LocaleProvider>
+              </ThemeProvider>
+            </ErrorBoundary>
+          </ObservabilityProvider>
+        </LoadingIndicatorProvider>
+      </ComponentsProvider>
+    </NonceContext.Provider>
   )
 }
 
diff --git a/src/contexts/NonceProvider/index.ts b/src/contexts/NonceProvider/index.ts
new file mode 100644
index 000000000..5fd59aa60
--- /dev/null
+++ b/src/contexts/NonceProvider/index.ts
@@ -0,0 +1 @@
+export { NonceContext, useNonce } from './useNonce'
diff --git a/src/contexts/NonceProvider/useNonce.test.tsx b/src/contexts/NonceProvider/useNonce.test.tsx
new file mode 100644
index 000000000..2ee7db230
--- /dev/null
+++ b/src/contexts/NonceProvider/useNonce.test.tsx
@@ -0,0 +1,19 @@
+import { renderHook } from '@testing-library/react'
+import { describe, test, expect } from 'vitest'
+import { NonceContext, useNonce } from './useNonce'
+
+describe('useNonce', () => {
+  test('returns undefined when no provider is present', () => {
+    const { result } = renderHook(() => useNonce())
+    expect(result.current).toBeUndefined()
+  })
+
+  test('returns the value supplied by NonceContext.Provider', () => {
+    const { result } = renderHook(() => useNonce(), {
+      wrapper: ({ children }) => (
+        <NonceContext.Provider value="csp-test-nonce">{children}</NonceContext.Provider>
+      ),
+    })
+    expect(result.current).toBe('csp-test-nonce')
+  })
+})
diff --git a/src/contexts/NonceProvider/useNonce.ts b/src/contexts/NonceProvider/useNonce.ts
new file mode 100644
index 000000000..cc5032f0a
--- /dev/null
+++ b/src/contexts/NonceProvider/useNonce.ts
@@ -0,0 +1,40 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * React context backing {@link useNonce}.
+ *
+ * @internal
+ */
+export const NonceContext = createContext<string | undefined>(undefined)
+
+/**
+ * Returns the CSP nonce supplied to {@link GustoProvider}, or `undefined` when none was provided.
+ *
+ * @remarks
+ * Use this when a custom UI component or partner-provided code injects a runtime `<style>` or
+ * `<script>` element and the integrating app serves a nonce-based Content Security Policy.
+ * Apply the returned value as the `nonce` property on the created element (e.g.
+ * `el.nonce = useNonce()`) before appending it to the document.
+ *
+ * @returns The active nonce, or `undefined` when {@link GustoProvider} was not given a `nonce`.
+ *
+ * @example
+ * ```tsx
+ * import { useNonce } from '@gusto/embedded-react-sdk'
+ *
+ * function InjectThemeStyles({ css }: { css: string }) {
+ *   const nonce = useNonce()
+ *   useEffect(() => {
+ *     const el = document.createElement('style')
+ *     if (nonce) el.nonce = nonce
+ *     el.textContent = css
+ *     document.head.appendChild(el)
+ *     return () => el.remove()
+ *   }, [css, nonce])
+ *   return null
+ * }
+ * ```
+ *
+ * @public
+ */
+export const useNonce = (): string | undefined => useContext(NonceContext)
diff --git a/src/contexts/ThemeProvider/ThemeProvider.test.tsx b/src/contexts/ThemeProvider/ThemeProvider.test.tsx
index 52f7c5e6d..7709c87c9 100644
--- a/src/contexts/ThemeProvider/ThemeProvider.test.tsx
+++ b/src/contexts/ThemeProvider/ThemeProvider.test.tsx
@@ -3,6 +3,7 @@ import { useEffect } from 'react'
 import { describe, test, expect, afterEach } from 'vitest'
 import { ThemeProvider } from './ThemeProvider'
 import { useTheme } from './useTheme'
+import { NonceContext } from '@/contexts/NonceProvider'
 
 describe('<ThemeProvider />', () => {
   afterEach(() => {
@@ -114,6 +115,36 @@ describe('<ThemeProvider />', () => {
     })
   })
 
+  describe('nonce', () => {
+    test('Applies the nonce from NonceContext to the injected style element', () => {
+      render(
+        <NonceContext.Provider value="csp-test-nonce">
+          <ThemeProvider>
+            <p>Child</p>
+          </ThemeProvider>
+        </NonceContext.Provider>,
+      )
+
+      const styleTag = document.head.querySelector<HTMLStyleElement>(
+        'style[data-testid="GSDK"]',
+      )
+      expect(styleTag?.nonce).toBe('csp-test-nonce')
+    })
+
+    test('Leaves nonce empty when no value is provided', () => {
+      render(
+        <ThemeProvider>
+          <p>Child</p>
+        </ThemeProvider>,
+      )
+
+      const styleTag = document.head.querySelector<HTMLStyleElement>(
+        'style[data-testid="GSDK"]',
+      )
+      expect(styleTag?.nonce).toBe('')
+    })
+  })
+
   test('Updates style tag textContent when theme changes', () => {
     const { rerender } = render(
       <ThemeProvider theme={{ colorPrimary: '#000' }}>
diff --git a/src/contexts/ThemeProvider/ThemeProvider.tsx b/src/contexts/ThemeProvider/ThemeProvider.tsx
index 2b4d9f563..39e1bea44 100644
--- a/src/contexts/ThemeProvider/ThemeProvider.tsx
+++ b/src/contexts/ThemeProvider/ThemeProvider.tsx
@@ -2,6 +2,7 @@ import type React from 'react'
 import { useCallback, useEffect, useMemo, useRef } from 'react'
 import { ThemeContext } from './useTheme'
 import { mergePartnerTheme, type GustoSDKTheme } from './theme'
+import { useNonce } from '@/contexts/NonceProvider'
 import '@/styles/sdk.scss'
 
 /** @internal */
@@ -26,6 +27,7 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
   portalContainer,
   children,
 }) => {
+  const nonce = useNonce()
   const GThemeVariables = useRef<HTMLStyleElement | null>(null)
   const portalContainerRef = useRef<HTMLElement | null>(null)
 
@@ -50,11 +52,12 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
     if (!GThemeVariables.current) {
       GThemeVariables.current = document.createElement('style')
       GThemeVariables.current.setAttribute('data-testid', 'GSDK')
+      if (nonce) GThemeVariables.current.nonce = nonce
       document.head.appendChild(GThemeVariables.current)
     }
 
     GThemeVariables.current.textContent = cssContent
-  }, [cssContent])
+  }, [cssContent, nonce])
 
   return (
     <ThemeContext.Provider value={{ container: portalContainerRef }}>
diff --git a/src/contexts/index.ts b/src/contexts/index.ts
index d930da31c..b3b980ee8 100644
--- a/src/contexts/index.ts
+++ b/src/contexts/index.ts
@@ -12,3 +12,4 @@ export * from './ComponentAdapter/componentAdapterTypes'
 export { ObservabilityProvider, useObservability } from './ObservabilityProvider'
 export type { ObservabilityProviderProps, ObservabilityContextValue } from './ObservabilityProvider'
 export type { GustoSDKTheme, GustoSDKThemeColors } from '@/contexts/ThemeProvider/theme'
+export { useNonce } from './NonceProvider'

From bbf6a53a64c0c2c943fac5dc1aed0517e42fd055 Mon Sep 17 00:00:00 2001
From: Jeff Johnson <jeff.johnson@gusto.com>
Date: Wed, 17 Jun 2026 12:26:24 -0700
Subject: [PATCH 2/3] fix: address CI feedback on CSP nonce PR

- prettier: collapse multi-line querySelector in ThemeProvider test
- tsdoc-coverage: reorder useNonce tags so @example is the final group
- markdownlint: add language tag to CSP example fenced block

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/getting-started/proxy-security-partner-guidance.md | 2 +-
 src/contexts/NonceProvider/useNonce.ts                  | 3 +--
 src/contexts/ThemeProvider/ThemeProvider.test.tsx       | 8 ++------
 3 files changed, 4 insertions(+), 9 deletions(-)

diff --git a/docs/getting-started/proxy-security-partner-guidance.md b/docs/getting-started/proxy-security-partner-guidance.md
index 627583cda..c498e72bc 100644
--- a/docs/getting-started/proxy-security-partner-guidance.md
+++ b/docs/getting-started/proxy-security-partner-guidance.md
@@ -113,7 +113,7 @@ function InjectedStyles({ css }: { css: string }) {
 
 ### Minimum policy
 
-```
+```http
 Content-Security-Policy:
   style-src 'self' 'nonce-XYZ';
   style-src-attr 'unsafe-inline';
diff --git a/src/contexts/NonceProvider/useNonce.ts b/src/contexts/NonceProvider/useNonce.ts
index cc5032f0a..45c867e2c 100644
--- a/src/contexts/NonceProvider/useNonce.ts
+++ b/src/contexts/NonceProvider/useNonce.ts
@@ -17,6 +17,7 @@ export const NonceContext = createContext<string | undefined>(undefined)
  * `el.nonce = useNonce()`) before appending it to the document.
  *
  * @returns The active nonce, or `undefined` when {@link GustoProvider} was not given a `nonce`.
+ * @public
  *
  * @example
  * ```tsx
@@ -34,7 +35,5 @@ export const NonceContext = createContext<string | undefined>(undefined)
  *   return null
  * }
  * ```
- *
- * @public
  */
 export const useNonce = (): string | undefined => useContext(NonceContext)
diff --git a/src/contexts/ThemeProvider/ThemeProvider.test.tsx b/src/contexts/ThemeProvider/ThemeProvider.test.tsx
index 7709c87c9..9993daea0 100644
--- a/src/contexts/ThemeProvider/ThemeProvider.test.tsx
+++ b/src/contexts/ThemeProvider/ThemeProvider.test.tsx
@@ -125,9 +125,7 @@ describe('<ThemeProvider />', () => {
         </NonceContext.Provider>,
       )
 
-      const styleTag = document.head.querySelector<HTMLStyleElement>(
-        'style[data-testid="GSDK"]',
-      )
+      const styleTag = document.head.querySelector<HTMLStyleElement>('style[data-testid="GSDK"]')
       expect(styleTag?.nonce).toBe('csp-test-nonce')
     })
 
@@ -138,9 +136,7 @@ describe('<ThemeProvider />', () => {
         </ThemeProvider>,
       )
 
-      const styleTag = document.head.querySelector<HTMLStyleElement>(
-        'style[data-testid="GSDK"]',
-      )
+      const styleTag = document.head.querySelector<HTMLStyleElement>('style[data-testid="GSDK"]')
       expect(styleTag?.nonce).toBe('')
     })
   })

From 83508526da733e85356b75614b4b2744fb242fe6 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 17 Jun 2026 19:31:49 +0000
Subject: [PATCH 3/3] chore: update derived files

---
 .reports/embedded-react-sdk.api.md |  4 +++
 docs/api/index.md                  | 44 ++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/.reports/embedded-react-sdk.api.md b/.reports/embedded-react-sdk.api.md
index e3cae5c63..370416b88 100644
--- a/.reports/embedded-react-sdk.api.md
+++ b/.reports/embedded-react-sdk.api.md
@@ -2500,6 +2500,7 @@ export interface GustoProviderProps {
     // Warning: (ae-forgotten-export) The symbol "LoadingIndicatorContextProps" needs to be exported by the entry point index.d.ts
     LoaderComponent?: LoadingIndicatorContextProps['LoadingIndicator'];
     locale?: string;
+    nonce?: string;
     portalContainer?: HTMLElement;
     queryClient?: QueryClient;
     theme?: Partial<GustoSDKTheme>;
@@ -5356,6 +5357,9 @@ export interface UseJobFormReady extends BaseFormHookReady<FieldsMetadata, JobFo
 // @public
 export type UseJobFormResult = HookLoadingResult | UseJobFormReady;
 
+// @public
+export const useNonce: () => string | undefined;
+
 // Warning: (ae-internal-missing-underscore) The name "useObservability" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal
diff --git a/docs/api/index.md b/docs/api/index.md
index d40f37b5e..437d1ccfe 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -98,6 +98,47 @@ return (
 )
 ```
 
+## Hooks
+
+<a id="usenonce"></a>
+
+### useNonce()
+
+> **useNonce**(): `string` \| `undefined`
+
+Returns the CSP nonce supplied to [GustoProvider](#gustoprovider), or `undefined` when none was provided.
+
+#### Returns
+
+`string` \| `undefined`
+
+The active nonce, or `undefined` when [GustoProvider](#gustoprovider) was not given a `nonce`.
+
+#### Remarks
+
+Use this when a custom UI component or partner-provided code injects a runtime `<style>` or
+`<script>` element and the integrating app serves a nonce-based Content Security Policy.
+Apply the returned value as the `nonce` property on the created element (e.g.
+`el.nonce = useNonce()`) before appending it to the document.
+
+#### Example
+
+```tsx
+import { useNonce } from '@gusto/embedded-react-sdk'
+
+function InjectThemeStyles({ css }: { css: string }) {
+  const nonce = useNonce()
+  useEffect(() => {
+    const el = document.createElement('style')
+    if (nonce) el.nonce = nonce
+    el.textContent = css
+    document.head.appendChild(el)
+    return () => el.remove()
+  }, [css, nonce])
+  return null
+}
+```
+
 ## Functions
 
 <a id="composeerrorhandler"></a>
@@ -1557,6 +1598,7 @@ you do not supply fall back to the SDK's built-in React Aria implementations.
 | <a id="property-gustoapipropslng"></a> `lng?` | `string` | Active i18next language. Defaults to `'en'`. |
 | <a id="property-gustoapipropsloadercomponent"></a> `LoaderComponent?` | (`__namedParameters`) => `Element` | Loading indicator rendered while SDK queries are pending. Overrides the SDK default spinner. |
 | <a id="property-gustoapipropslocale"></a> `locale?` | `string` | BCP 47 locale used for number, date, and currency formatting throughout the SDK. Defaults to `'en-US'`. |
+| <a id="property-gustoapipropsnonce"></a> `nonce?` | `string` | CSP nonce to apply to runtime-injected `<style>` elements (theming, PDF download window). Pass the same per-request nonce your app uses in its `style-src 'nonce-…'` directive. Also exposed to custom UI components via `useNonce`. |
 | <a id="property-gustoapipropsportalcontainer"></a> `portalContainer?` | `HTMLElement` | Element to use as the portal container for SDK popovers and dropdowns. Useful when rendering inside a modal or shadow root. |
 | <a id="property-gustoapipropsqueryclient"></a> `queryClient?` | `QueryClient` | Optional TanStack Query `QueryClient` to share with the rest of your app. When omitted, the SDK creates its own client configured for Gusto's API. |
 | <a id="property-gustoapipropstheme"></a> `theme?` | `Partial`\<[`GustoSDKTheme`](#gustosdktheme)\> | Theme overrides applied to SDK components. See [GustoSDKTheme](#gustosdktheme). |
@@ -1585,6 +1627,7 @@ Props for [GustoProviderCustomUIAdapter](#gustoprovidercustomuiadapter).
 | <a id="property-gustoprovidercustomuiadapterpropslng"></a> `lng?` | `string` | Active i18next language. Defaults to `'en'`. |
 | <a id="property-gustoprovidercustomuiadapterpropsloadercomponent"></a> `LoaderComponent?` | (`__namedParameters`) => `Element` | Loading indicator rendered while SDK queries are pending. Overrides the SDK default spinner. |
 | <a id="property-gustoprovidercustomuiadapterpropslocale"></a> `locale?` | `string` | BCP 47 locale used for number, date, and currency formatting throughout the SDK. Defaults to `'en-US'`. |
+| <a id="property-gustoprovidercustomuiadapterpropsnonce"></a> `nonce?` | `string` | CSP nonce to apply to runtime-injected `<style>` elements (theming, PDF download window). Pass the same per-request nonce your app uses in its `style-src 'nonce-…'` directive. Also exposed to custom UI components via `useNonce`. |
 | <a id="property-gustoprovidercustomuiadapterpropsportalcontainer"></a> `portalContainer?` | `HTMLElement` | Element to use as the portal container for SDK popovers and dropdowns. Useful when rendering inside a modal or shadow root. |
 | <a id="property-gustoprovidercustomuiadapterpropsqueryclient"></a> `queryClient?` | `QueryClient` | Optional TanStack Query `QueryClient`. When omitted, the SDK creates its own client configured for Gusto's API. |
 | <a id="property-gustoprovidercustomuiadapterpropstheme"></a> `theme?` | `Partial`\<[`GustoSDKTheme`](#gustosdktheme)\> | Theme overrides applied to SDK components. See [GustoSDKTheme](#gustosdktheme). |
@@ -1612,6 +1655,7 @@ Shared configuration props accepted by [GustoProvider](#gustoprovider) and [Gust
 | <a id="property-gustoproviderpropslng"></a> `lng?` | `string` | Active i18next language. Defaults to `'en'`. |
 | <a id="property-gustoproviderpropsloadercomponent"></a> `LoaderComponent?` | (`__namedParameters`) => `Element` | Loading indicator rendered while SDK queries are pending. Overrides the SDK default spinner. |
 | <a id="property-gustoproviderpropslocale"></a> `locale?` | `string` | BCP 47 locale used for number, date, and currency formatting throughout the SDK. Defaults to `'en-US'`. |
+| <a id="property-gustoproviderpropsnonce"></a> `nonce?` | `string` | CSP nonce to apply to runtime-injected `<style>` elements (theming, PDF download window). Pass the same per-request nonce your app uses in its `style-src 'nonce-…'` directive. Also exposed to custom UI components via `useNonce`. |
 | <a id="property-gustoproviderpropsportalcontainer"></a> `portalContainer?` | `HTMLElement` | Element to use as the portal container for SDK popovers and dropdowns. Useful when rendering inside a modal or shadow root. |
 | <a id="property-gustoproviderpropsqueryclient"></a> `queryClient?` | `QueryClient` | Optional TanStack Query `QueryClient`. When omitted, the SDK creates its own client configured for Gusto's API. |
 | <a id="property-gustoproviderpropstheme"></a> `theme?` | `Partial`\<[`GustoSDKTheme`](#gustosdktheme)\> | Theme overrides applied to SDK components. See [GustoSDKTheme](#gustosdktheme). |