hermes-config/skills/self-hosting/shop-pro-quote/references/csp-wasm-libraries.md

CSP for WASM / Web Worker Libraries

SPQ pages use <meta http-equiv="Content-Security-Policy"> tags with restrictive defaults. When adding client-side libraries that use WebAssembly or Web Workers (Tesseract.js, ONNX runtime, etc.), the CSP MUST be updated or the library silently fails.

Required CSP Directives

script-src — add 'unsafe-eval'

WASM compilation uses new Function() / eval() internally. Without it:

'unsafe-eval' is not allowed source of script in ... "script-src 'self' 'unsafe-inline'"

connect-src — add CDN origin + blob:

Web Workers download WASM cores and data files (e.g. eng.traineddata) from CDN via fetch(). Blob URLs are needed for worker communication.

Without CDN:

Tesseract.min.js.map - violates ... "connect-src 'self'"

Without blob::

Refused to connect to 'blob:...' because it violates ... "connect-src"

worker-src — add blob:

Inline Web Workers created via new Worker(URL.createObjectURL(blob)) need blob: in worker-src.

Full CSP Template

<meta http-equiv="Content-Security-Policy" content="
    default-src 'self';
    script-src 'self' 'unsafe-inline' 'unsafe-eval'
        https://cdn.tailwindcss.com https://cdn.jsdelivr.net
        https://cdnjs.cloudflare.com https://fonts.googleapis.com https://www.gstatic.com;
    style-src 'self' 'unsafe-inline'
        https://cdn.tailwindcss.com https://fonts.googleapis.com;
    font-src https://fonts.gstatic.com;
    connect-src 'self' https://cdn.jsdelivr.net blob:;
    img-src 'self' data: blob:;
    worker-src blob:;
    frame-src 'self';
">

Diagnosis Pattern

When a WASM/worker library silently hangs with no console errors visible at first glance:

1. Open F12 → Console and look for CSP violation messages (they appear as warnings, not errors)
2. They say exactly which directive was violated and which resource was blocked
3. Add the missing origin/blob: to the relevant directive
4. Hard refresh (Ctrl+Shift+R) to bypass <meta> tag cache

Common silent-failure symptoms:

• Tesseract.js: "Running OCR..." forever (worker can't download WASM/traineddata)
• ONNX: Model loading hangs (can't fetch .onnx from CDN)
• Any WASM: White screen or stuck spinner (WASM compilation blocked)

Pages Affected

Every SPQ page has its own <meta> CSP tag:

Page	CSP needed?
appointments.html	Yes (Tesseract.js)
index.html	Minimal (no WASM)
customers.html	Minimal
login.html	Minimal
repair-orders.html	Minimal (but has AI features via api.js)

Only update CSP on pages that actually load WASM/worker libraries. Over-restricting is fine; over-permissing is not.