Skip to main content

Prepare security and production controls

The Website Widget is a public browser surface, not a trusted application boundary. Server policy and the allowed HTTPS origin remain authoritative for every session, identity, message, form, media, navigation, and screenshot operation.

Origin, transport, and content security​

  • Serve the host page and Widget through HTTPS. Missing, malformed, local, file:, data:, javascript:, or unapproved Origin values fail closed.
  • Send X-Qanivo-Widget-Version: 1.0 and use Authorization: Bearer only for short-lived grants; never put grants in URLs.
  • Configure CSP for the published script, API, and approved media/SSE hosts. Use the package’s style nonce for the legacy stylesheet fallback; do not add style-src 'unsafe-inline' just to make the Widget work.
  • Prefer the package’s Shadow DOM/adopted stylesheet path so host CSS cannot rewrite controls. Test the legacy fallback separately with the required nonce.
  • Do not expose signing secrets, provider credentials, raw provider payloads, screenshot bytes, or unrestricted diagnostics in the browser bundle, public errors, logs, or Event Hooks.

Bounds and allowlists​

Configure the narrowest server policy for payload sizes, message lengths, form fields, history windows, event replay, reconnect attempts, media bytes, dimensions, and attachment types. Backend limits override browser options.

Navigation commands are prompt-only and must match the backend allowlist. The Widget must reject credentials, non-HTTPS destinations, unlisted domains, and wildcard apex confusion before acknowledging a command.

Media URLs must use approved public hosts or authenticated Qanivo media delivery. Screenshot capture is visitor-controlled: each request opens an isolated consent prompt, captures only the visitor-selected surface, uploads through the bounded scanning/quarantine path, and records the acknowledgement. A host callback must not silently capture the desktop or page.

Identity, privacy, and logout​

Generate identity assertions on the host server. Bind them to an external subject, expiry, nonce, audience, and replay policy. Call clearIdentity() or resetVisitor() when an authenticated host user logs out or changes account.

Page context is minimized and untrusted. Allow only named scalar query keys, redact sensitive names, and exclude full query strings, hashes, referrers, credentials, authorization/reset/invitation values, arbitrary DOM content, and private customer records.

Accessibility and localization​

Test the installed Widget with English and Arabic, LTR and RTL, keyboard-only navigation, screen readers, focus containment/restoration, visible focus, touch targets, forced colors, and reduced motion. Do not infer accessibility from the host page. Ensure an isolated consent dialog is operable and that terminal/error states have actionable localized text.

Safe diagnostics and production readiness​

Record the stable error code, retryability, terminal state, and correlation ID. Keep raw request/response bodies and grants out of browser console output and telemetry. Correlate a support report with the safe correlation ID rather than a secret or internal provider identifier.

Before production release, verify at minimum:

  1. unapproved-origin and cross-Workspace denial;
  2. grant expiry, renewal, revocation, and ban behavior;
  3. identity assertion replay protection;
  4. message idempotency and POST/SSE/history reconciliation;
  5. rate bounds, media scanning, screenshot consent, and navigation allowlists;
  6. CSP, Shadow DOM, keyboard, screen-reader, RTL, and reduced-motion behavior;
  7. safe error envelopes and correlation propagation.

These controls align with the Website Widget public contract, the security policy for origin/grant/navigation/screenshot handling, and the operations requirements for safe diagnostics and release gates. They do not certify provider or production readiness by themselves.

Authority references​