feat: add CSP nonce support (#395)

Add cspNonce for usePlaidLink and PlaidEmbeddedLink so integrators with
nonce-based CSPs can pass the per-response nonce to the Plaid script tag.

Author: ssantichaivekin-plaid

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- Add `cspNonce` to support nonce-based Content Security Policies on `usePlaidLink` and `PlaidEmbeddedLink`.
+
 ## 4.1.1 
 
 - Fix build issue from version 4.1.0

README.md

@@ -85,6 +85,41 @@ the various Link options and the
 | `onEvent`             | `(eventName: PlaidLinkStableEvent \| string, metadata: PlaidLinkOnEventMetadata) => void` |
 | `onLoad`              | `() => void`                                                                              |
 | `receivedRedirectUri` | `string \| null \| undefined`                                                             |
+| `cspNonce`            | `string \| undefined`                                                                     |
+
+#### Content Security Policy nonce
+
+If your app uses a nonce-based Content Security Policy, generate a fresh nonce
+per page response and pass it as `cspNonce`
+on `usePlaidLink` or `PlaidEmbeddedLink`. Only mount these components once
+`cspNonce` is known.
+
+Allow that nonce in `script-src`, `style-src`, and `style-src-elem`. Link still
+requires `style-src-attr 'unsafe-inline'` today. You will also need `frame-src` and `connect-src` as
+[documented for Link Web](https://plaid.com/docs/link/web/#csp-guidance); for
+example:
+
+```html
+default-src https://cdn.plaid.com/;
+script-src 'nonce-<PAGE_RESPONSE_NONCE>' https://cdn.plaid.com/link/v2/stable/link-initialize.js;
+style-src 'nonce-<PAGE_RESPONSE_NONCE>';
+style-src-elem 'nonce-<PAGE_RESPONSE_NONCE>';
+style-src-attr 'unsafe-inline';
+frame-src https://cdn.plaid.com/;
+connect-src https://production.plaid.com/;
+```
+
+If you omit `cspNonce`, behavior is unchanged (including for embedded Link).
+
+```tsx
+const { open, ready } = usePlaidLink({
+  token: '<GENERATED_LINK_TOKEN>',
+  cspNonce: '<PER_RESPONSE_NONCE>',
+  onSuccess: (public_token, metadata) => {
+    // send public_token to server
+  },
+});
+```
 
 #### `usePlaidLink` return value
 

src/PlaidEmbeddedLink.test.tsx

@@ -50,4 +50,31 @@ describe('PlaidEmbeddedLink', () => {
     rerender(<PlaidEmbeddedLink {...newConfig} />);
     expect(createEmbeddedSpy).toHaveBeenCalledTimes(2);
   });
+
+  it('should load the Plaid script without a nonce when cspNonce is omitted', () => {
+    mockedUseScript.mockClear();
+    render(<PlaidEmbeddedLink {...config} />);
+
+    expect(mockedUseScript).toHaveBeenCalledWith({
+      src: 'https://cdn.plaid.com/link/v2/stable/link-initialize.js',
+      checkForExisting: true,
+    });
+    expect(createEmbeddedSpy.mock.calls[0][0]).not.toHaveProperty('cspNonce');
+  });
+
+  it('should pass cspNonce to the Plaid script tag only', () => {
+    mockedUseScript.mockClear();
+    createEmbeddedSpy.mockClear();
+    render(<PlaidEmbeddedLink {...config} cspNonce="test-csp-nonce" />);
+
+    expect(mockedUseScript).toHaveBeenCalledWith({
+      src: 'https://cdn.plaid.com/link/v2/stable/link-initialize.js',
+      checkForExisting: true,
+      nonce: 'test-csp-nonce',
+    });
+    expect(createEmbeddedSpy).toHaveBeenCalledWith(
+      expect.not.objectContaining({ cspNonce: 'test-csp-nonce' }),
+      expect.any(HTMLElement)
+    );
+  });
 });

src/PlaidEmbeddedLink.tsx

@@ -35,6 +35,7 @@ export const PlaidEmbeddedLink = (props: PlaidEmbeddedLinkPropTypes) => {
   const [loading, error] = useScript({
     src: PLAID_LINK_STABLE_URL,
     checkForExisting: true,
+    ...(props.cspNonce ? { nonce: props.cspNonce } : {}),
   });
 
   const embeddedLinkTarget = useRef<HTMLDivElement | null>(null);
@@ -59,7 +60,8 @@ export const PlaidEmbeddedLink = (props: PlaidEmbeddedLinkPropTypes) => {
     // its Plaid Link instance because the embedded Link integration in link-initialize
     // maintains its own handler internally.
     const { destroy } = window.Plaid.createEmbedded(
-      { ...config }, embeddedLinkTarget.current as HTMLElement
+      { ...config },
+      embeddedLinkTarget.current as HTMLElement
     );
 
     // Clean up embedded Link component on unmount

src/types/index.ts

@@ -101,6 +101,9 @@ export interface CommonPlaidLinkOptions<T> {
   // A callback that is called during a user's flow in Link.
   // See all values for eventName here https://plaid.com/docs/link/web/#link-web-onevent-eventName
   onEvent?: PlaidLinkOnEvent;
+  // Sets the nonce attribute on the dynamically inserted Plaid Link script tag.
+  // Use this to support nonce-based Content Security Policies.
+  cspNonce?: string;
 }
 
 /**

src/usePlaidLink.test.tsx

@@ -37,9 +37,10 @@ describe('usePlaidLink', () => {
   };
 
   beforeEach(() => {
+    mockedUseScript.mockClear();
     mockedUseScript.mockImplementation(() => ScriptLoadingState.LOADED);
     window.Plaid = {
-      create: ({ onLoad }) => {
+      create: jest.fn(({ onLoad }) => {
         onLoad && onLoad();
         return {
           create: jest.fn(),
@@ -48,7 +49,7 @@ describe('usePlaidLink', () => {
           exit: jest.fn(),
           destroy: jest.fn(),
         };
-      },
+      }),
       open: jest.fn(),
       submit: jest.fn(),
       exit: jest.fn(),
@@ -67,6 +68,19 @@ describe('usePlaidLink', () => {
     expect(screen.getByText(ReadyState.NO_ERROR));
   });
 
+  it('should pass cspNonce to the Plaid script tag only', async () => {
+    render(<HookComponent config={{ ...config, cspNonce: 'test-csp-nonce' }} />);
+
+    expect(mockedUseScript).toHaveBeenCalledWith({
+      src: 'https://cdn.plaid.com/link/v2/stable/link-initialize.js',
+      checkForExisting: true,
+      nonce: 'test-csp-nonce',
+    });
+    expect(window.Plaid.create).toHaveBeenCalledWith(
+      expect.not.objectContaining({ cspNonce: 'test-csp-nonce' })
+    );
+  });
+
   it('should render with publicKey', async () => {
     const configWithPubKey: PlaidLinkOptions = {
       publicKey: 'test-public-key',

src/usePlaidLink.ts

@@ -26,6 +26,7 @@ export const usePlaidLink = (options: PlaidLinkOptions) => {
   const [loading, error] = useScript({
     src: PLAID_LINK_STABLE_URL,
     checkForExisting: true,
+    ...(options.cspNonce ? { nonce: options.cspNonce } : {}),
   });
 
   // internal state
@@ -63,9 +64,10 @@ export const usePlaidLink = (options: PlaidLinkOptions) => {
       plaid.exit({ force: true }, () => plaid.destroy());
     }
 
+    const { cspNonce: _cspNonce, ...linkOptions } = options;
     const next = createPlaid(
       {
-        ...options,
+        ...linkOptions,
         onLoad: () => {
           setIframeLoaded(true);
           options.onLoad && options.onLoad();