Development Guide: CSP Deployment Guide

This guide is for integrating office-sdk behind enterprise intranets, portal systems, or security gateways. It describes the minimum deployment requirements and common adjustments under Content-Security-Policy.

Use Cases

If the integrating page uses CSP, confirm before release that the SDK static asset directory, document file sources, and page script policy are all allowlisted. The SDK loads ES Modules, styles, Workers, SharedWorkers, WebAssembly, images, fonts, and other resources. An overly narrow CSP can cause documents to fail to open or render a blank area.

Recommended Starting Policy

The policy below assumes:

• The complete SDK lib/ directory is deployed on the same origin as the integrating page, for example /office-sdk/
• Document files are loaded from the same origin or from explicitly allowlisted file-hosting domains
• The integrating page loads the SDK through an external type="module" script or dynamic import(), and does not rely on inline script

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'wasm-unsafe-eval' 'unsafe-eval';
  script-src-elem 'self';
  worker-src 'self';
  child-src 'self';
  style-src 'self' 'unsafe-inline';
  font-src 'self' data:;
  img-src 'self' data: blob:;
  connect-src 'self' https://<file-host>;
  object-src 'none';
  base-uri 'self';

Replace https://<file-host> with the actual domain for document files, images, or authentication APIs. If all files are same-origin, you can remove the placeholder domain.

Directive Notes

Directive	Usually Required	Description
script-src 'self'	Yes	Allows loading UI.js, preload.js, split runtime modules, and wasm JS glue files.
'wasm-unsafe-eval'	Yes	Allows the browser to compile and instantiate WebAssembly.
'unsafe-eval'	Compatibility	Used for compatibility with browsers or security policies that classify WebAssembly runtime differently. If enterprise security rules disallow it, validate CSP in target browsers first.
script-src-elem 'self'	Recommended	If the enterprise policy explicitly sets script-src-elem, same-origin module scripts must be allowed.
worker-src 'self'	Yes	The SDK loads module Workers and SharedWorkers from the static worker/ directory by default.
child-src 'self'	Recommended	Fallback for some older browsers or CSP implementations that apply child-src to Workers.
style-src 'self' 'unsafe-inline'	Yes	The SDK loads style.css, and runtime components write necessary inline styles.
font-src 'self' data:	Recommended	Allows SDK and document rendering fonts, including embedded font data.
img-src 'self' data: blob:	Yes	Document images, previews, exported images, and temporary object URLs include data: or blob: URLs.
connect-src	Application-specific	Add the corresponding domains when opening remote document URLs, requesting authentication APIs, or loading cross-origin resources.
object-src 'none'	Recommended	The SDK does not depend on <object>; disabling it is recommended.
base-uri 'self'	Recommended	Limits the risk of injected <base> tags.

When blob: Is Needed

The SDK uses static Worker URLs by default, so worker-src 'self' is enough for the basic configuration. Add blob: to worker-src and child-src only when:

• The integrator rewrites Worker URLs to blob: URLs
• The host page or micro-frontend framework wraps Workers as Blob Workers
• An enterprise proxy or security container requires Worker scripts to be injected through Blob URLs

Example:

worker-src 'self' blob:;
child-src 'self' blob:;

Inline Script Recommendations

The SDK itself does not require script-src 'unsafe-inline'. If the integrating page needs inline bootstrap script, prefer nonce or hash:

script-src 'self' 'wasm-unsafe-eval' 'unsafe-eval' 'nonce-<random>';

Example page script:

<script type="module" nonce="<random>">
  import OfficeSdk from "/office-sdk/UI.js";
</script>

If enterprise security rules forbid inline script, put the integration code in a separate .js file and load it as a same-origin module script.

Cross-Origin Deployment Notes

The current SDK creates its SharedWorker directly with new SharedWorker(workerUrl). SharedWorkers apply strict same-origin rules to their script URL, so CSP and CORS configuration alone cannot guarantee that the complete SDK will run cross-origin.

Recommended deployment:

• Deploy the complete lib/ directory on the same origin as the host page
• Or reverse-proxy the SDK assets through the host origin so /office-sdk/worker/ appears same-origin to the page
• Keep the complete worker/, worker/wasm/, locale-assets/, and vendor/ directory structure
• Serve .wasm files with the application/wasm MIME type

ES Modules, styles, and document URLs follow browser cross-origin rules, but that does not make a cross-origin SharedWorker valid. Test an actual document open on the final domain with the final CSP and target browser before release.

Common CSP Troubleshooting

Symptom	Cause	Fix
Refused to load the script	script-src or script-src-elem does not allow the SDK asset domain.	Add the SDK static asset domain and confirm that UI.js and runtime chunks are accessible.
Refused to create a worker	worker-src does not allow the source, or the SharedWorker script is cross-origin.	Allow same-origin Workers and deploy or reverse-proxy worker/ through the host origin. If using Blob Workers, also add blob:.
Refused to compile or instantiate WebAssembly	Missing 'wasm-unsafe-eval', or the browser only recognizes 'unsafe-eval'.	Add 'wasm-unsafe-eval' to script-src; keep 'unsafe-eval' if needed.
Document images are missing	img-src does not allow data: or blob:.	Add data: and blob: to img-src.
Styles are broken	style-src does not allow style.css or inline styles.	Allow the SDK style domain and keep 'unsafe-inline'.
Remote documents fail to open	connect-src does not allow the file-hosting domain or authentication API domain.	Add the required file-hosting and authentication API domains to connect-src.

Release Checklist

• The complete lib/ directory is deployed, not only UI.js
• style.css, worker/, worker/wasm/, locale-assets/, and vendor/ are directly accessible
• CSP allows the SDK static asset domain
• CSP allows the directives required by Workers and WebAssembly
• The SharedWorker script is same-origin with the host page
• The target browser allows SharedWorker and IndexedDB
• The server returns application/wasm for .wasm files
• Remote document URLs, auth APIs, and image domains are added to connect-src / img-src
• The browser DevTools Console has no CSP violations