CSP Integration Guide

This guide covers how to integrate the SmartCapture Web SDK in applications that enforce Content Security Policy (CSP) headers. It applies exclusively to the CSP-compatible package (gbgplc-smartcapture-web-csp-compatible-vX.Y.Z.tgz).

---

Installation

Install the CSP-compatible package instead of the standard one:

npm install file:./gbgplc-smartcapture-web-csp-compatible-vX.Y.Z.tgz

---

Additional Setup Steps

The CSP-compatible version requires two setup steps that the standard package does not.

1. Copy the idlive-capture folder to your public directory

The face detection engine relies on static assets (WebAssembly modules, a Web Worker, and models) that must be served from your application’s public directory. Copy them from the installed package:

cp -r ./node_modules/idlive-face-capture-web/idlive-capture ./public/idlive-capture

Note: Repeat this step whenever you upgrade the package to ensure the assets stay in sync.

The SDK expects these files to be available at /idlive-capture.

2. Add the face detection script to your HTML

The face detection engine must be loaded as a plain <script> tag — it cannot go through your bundler. Add the following to your HTML <head> before your application scripts:

<script src="/idlive-capture/face.js"></script>

Note: The src must match the location where you copied the assets.

---

Required CSP Directives

Add the following directives to your Content-Security-Policy header:

default-src 'self';
base-uri 'self';
frame-ancestors 'none';
object-src 'none';
form-action 'self';

script-src 'self' 'wasm-unsafe-eval';
script-src-elem 'self';
script-src-attr 'none';

style-src 'self';
style-src-elem 'self' 'unsafe-inline';
style-src-attr 'none';

img-src 'self' data: blob:;
font-src 'self';
media-src 'self' blob:;
connect-src 'self' data:;
worker-src 'self' blob:;
manifest-src 'self';

Directive Reference

Directive	Required Value(s)	Purpose
script-src	'self' 'wasm-unsafe-eval'	Load SDK scripts and WebAssembly modules
script-src-elem	'self'	Load external script files
script-src-attr	'none'	Block inline event handlers
style-src-elem	'self' 'unsafe-inline'	Face detection library inline styles — see Known Limitations
style-src-attr	'none'	Block inline style attributes
img-src	'self' data: blob:	Camera previews and animations
media-src	'self' blob:	Camera video streams
connect-src	'self' data:	Internal data processing
worker-src	'self' blob:	Web Workers for face detection

---

Server Configuration Examples

nginx

server {
  listen 443 ssl;
  server_name yourdomain.com;

  add_header Content-Security-Policy "
    default-src 'self';
    base-uri 'self';
    frame-ancestors 'none';
    object-src 'none';
    form-action 'self';
    script-src 'self' 'wasm-unsafe-eval';
    script-src-elem 'self';
    script-src-attr 'none';
    style-src 'self';
    style-src-elem 'self' 'unsafe-inline';
    style-src-attr 'none';
    img-src 'self' data: blob:;
    font-src 'self';
    media-src 'self' blob:;
    connect-src 'self' data:;
    worker-src 'self' blob:;
    manifest-src 'self';
  " always;
}

Apache

<IfModule mod_headers.c>
  Header always set Content-Security-Policy "\
    default-src 'self'; \
    base-uri 'self'; \
    frame-ancestors 'none'; \
    object-src 'none'; \
    form-action 'self'; \
    script-src 'self' 'wasm-unsafe-eval'; \
    script-src-elem 'self'; \
    script-src-attr 'none'; \
    style-src 'self'; \
    style-src-elem 'self' 'unsafe-inline'; \
    style-src-attr 'none'; \
    img-src 'self' data: blob:; \
    font-src 'self'; \
    media-src 'self' blob:; \
    connect-src 'self' data:; \
    worker-src 'self' blob:; \
    manifest-src 'self';"
</IfModule>

Node.js / Express

const helmet = require('helmet');

app.use(
  helmet.contentSecurityPolicy({
    directives: {
      defaultSrc: ["'self'"],
      baseUri: ["'self'"],
      frameAncestors: ["'none'"],
      objectSrc: ["'none'"],
      formAction: ["'self'"],
      scriptSrc: ["'self'", "'wasm-unsafe-eval'"],
      scriptSrcElem: ["'self'"],
      scriptSrcAttr: ["'none'"],
      styleSrc: ["'self'"],
      styleSrcElem: ["'self'", "'unsafe-inline'"],
      styleSrcAttr: ["'none'"],
      imgSrc: ["'self'", "data:", "blob:"],
      fontSrc: ["'self'"],
      mediaSrc: ["'self'", "blob:"],
      connectSrc: ["'self'", "data:"],
      workerSrc: ["'self'", "blob:"],
      manifestSrc: ["'self'"],
    },
  })
);

---

Known Limitations

Inline style injection (style-src-elem 'unsafe-inline')

The face detection library injects a small inline <style> element into the document. This triggers a CSP report for style-src-elem even when 'unsafe-inline' is included in the policy.

This does not break functionality — the violation is logged as a warning only and the camera operates normally. It is a known limitation of the current version of the underlying face detection library and does not affect the security posture of your application in a meaningful way, given that:

• It is limited to style-src-elem only — inline style="" attributes remain fully blocked via style-src-attr 'none'
• The injected style is static and non-executable

We are tracking this with our vendor and expect it to be resolved in a future release.

---

Checklist

Before going to production:

• Installed the CSP-compatible package (gbgplc-smartcapture-web-csp-compatible-vX.Y.Z.tgz)
• Copied the idlive-capture folder to your public directory
• Added <script src="/idlive-capture/face.js"></script> to your HTML <head> before your application scripts
• Configured all required CSP directives on your web server
• Tested with Content-Security-Policy-Report-Only first
• Verified face camera works end-to-end (initialization → detection → capture)
• Switched to enforcing mode (Content-Security-Policy)