Skip to main content

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​

DirectiveRequired 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)