initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,83 @@
+# 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
+
+```html
+<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.