feat(#6,#7): CSP directive catalog + nonce + defer/consent strategies

- src/csp.ts (ahize/csp sub-path): per-provider CspDirectives catalog
  (script/connect/frame/style/img/font/media-src) including every WSS
  endpoint competitor wrappers forget (nexus-websocket-a/b.intercom.io,
  client.relay.crisp.chat, widget-mediator.zopim.com, <host>/cable for
  Chatwoot). mergeCsp(), toHeaderString() and watchCspViolations() helpers.
- nonce forwarded to every injected <script> tag via options.nonce.
- BaseLoadOptions adds defer ('immediate'|'idle'|'interaction'|'manual')
  and consent (boolean gate). waitForDefer() uses requestIdleCallback with
  setTimeout(200) fallback, pointerdown/scroll/keydown/touchstart with
  10s fallback for 'interaction', blocks forever for 'manual'.
- consent: false short-circuits load() before any script injection.
- Tests: CSP header construction, merge dedup, chatwoot self-hosted host,
  defer immediate/idle/interaction timings, consent gate.

Preempts: crisp-sdk-web#5/#31, react-zendesk#35, vue-zendesk#36,
react-use-intercom#237/#364/#741, adamsoffer/react-hubspot#6,
react-use-hubspot-form#44.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: productdevbook

package.json

@@ -75,6 +75,10 @@
     "./server": {
       "types": "./dist/server.d.mts",
       "default": "./dist/server.mjs"
+    },
+    "./csp": {
+      "types": "./dist/csp.d.mts",
+      "default": "./dist/csp.mjs"
     }
   },
   "scripts": {

src/_defer.ts

@@ -0,0 +1,54 @@
+import { isBrowser } from "./_loader.ts";
+
+export type DeferStrategy = "immediate" | "idle" | "interaction" | "manual";
+
+interface WindowWithIdle {
+  requestIdleCallback?: (cb: () => void, opts?: { timeout?: number }) => number;
+  cancelIdleCallback?: (id: number) => void;
+  setTimeout: (cb: () => void, ms: number) => number;
+  clearTimeout: (id: number) => void;
+  addEventListener?: (type: string, listener: () => void, opts?: unknown) => void;
+  removeEventListener?: (type: string, listener: () => void, opts?: unknown) => void;
+}
+
+function win(): WindowWithIdle | undefined {
+  if (!isBrowser()) return undefined;
+  return globalThis as unknown as WindowWithIdle;
+}
+
+const INTERACTION_EVENTS = ["pointerdown", "scroll", "keydown", "touchstart"] as const;
+
+export function waitForDefer(strategy: DeferStrategy, timeoutMs = 10_000): Promise<void> {
+  if (strategy === "immediate") return Promise.resolve();
+  if (strategy === "manual") return new Promise(() => {});
+  const w = win();
+  if (!w) return Promise.resolve();
+
+  if (strategy === "idle") {
+    return new Promise<void>((resolve) => {
+      if (w.requestIdleCallback) {
+        w.requestIdleCallback(() => resolve(), { timeout: timeoutMs });
+      } else {
+        w.setTimeout(() => resolve(), 200);
+      }
+    });
+  }
+
+  return new Promise<void>((resolve) => {
+    let settled = false;
+    const off: Array<() => void> = [];
+    const cleanup = () => {
+      if (settled) return;
+      settled = true;
+      for (const fn of off) fn();
+      resolve();
+    };
+    for (const evt of INTERACTION_EVENTS) {
+      const handler = () => cleanup();
+      w.addEventListener?.(evt, handler, { once: true, passive: true });
+      off.push(() => w.removeEventListener?.(evt, handler));
+    }
+    const timer = w.setTimeout(cleanup, timeoutMs);
+    off.push(() => w.clearTimeout(timer));
+  });
+}

src/_types.ts

@@ -30,9 +30,21 @@ export type IdentityState = { kind: "anonymous" } | { kind: "identified"; identi
 
 export type IdentityListener = (next: IdentityState, prev: IdentityState) => void;
 
+export type DeferStrategy = "immediate" | "idle" | "interaction" | "manual";
+
 export interface BaseLoadOptions {
   nonce?: string;
   autoShow?: boolean;
+  /**
+   * When to actually inject the CDN script:
+   * - "immediate" (default): inject right away
+   * - "idle": requestIdleCallback + 200ms fallback
+   * - "interaction": first pointerdown/scroll/keydown/touchstart
+   * - "manual": the returned Promise never resolves; consumer must call resume()
+   */
+  defer?: DeferStrategy;
+  /** Consent gate. If false, load() resolves without injecting. Default: true. */
+  consent?: boolean;
 }
 
 export interface LoadOptions extends BaseLoadOptions {

src/csp.ts

@@ -0,0 +1,203 @@
+import type { ProviderName } from "./_types.ts";
+
+export type CspDirectiveKey =
+  | "script-src"
+  | "connect-src"
+  | "frame-src"
+  | "style-src"
+  | "img-src"
+  | "font-src"
+  | "media-src";
+
+export type CspDirectives = Record<CspDirectiveKey, readonly string[]>;
+
+const EMPTY: CspDirectives = {
+  "script-src": [],
+  "connect-src": [],
+  "frame-src": [],
+  "style-src": [],
+  "img-src": [],
+  "font-src": [],
+  "media-src": [],
+};
+
+const CATALOG: Partial<Record<ProviderName, CspDirectives>> = {
+  intercom: {
+    "script-src": ["https://widget.intercom.io", "https://js.intercomcdn.com"],
+    "connect-src": [
+      "https://api-iam.intercom.io",
+      "https://api-ping.intercom.io",
+      "https://nexus-websocket-a.intercom.io",
+      "https://nexus-websocket-b.intercom.io",
+      "wss://nexus-websocket-a.intercom.io",
+      "wss://nexus-websocket-b.intercom.io",
+      "https://uploads.intercomcdn.com",
+      "https://uploads.intercomusercontent.com",
+    ],
+    "frame-src": ["https://intercom-sheets.com", "https://www.intercom-reporting.com"],
+    "style-src": ["https://fonts.intercomcdn.com"],
+    "img-src": ["https://js.intercomcdn.com", "https://static.intercomassets.com"],
+    "font-src": ["https://fonts.intercomcdn.com"],
+    "media-src": ["https://js.intercomcdn.com"],
+  },
+  crisp: {
+    "script-src": ["https://client.crisp.chat"],
+    "connect-src": [
+      "https://client.crisp.chat",
+      "https://client.relay.crisp.chat",
+      "wss://client.relay.crisp.chat",
+      "https://storage.crisp.chat",
+    ],
+    "frame-src": ["https://game.crisp.chat"],
+    "style-src": ["https://client.crisp.chat"],
+    "img-src": [
+      "https://client.crisp.chat",
+      "https://image.crisp.chat",
+      "https://storage.crisp.chat",
+    ],
+    "font-src": ["https://client.crisp.chat"],
+    "media-src": ["https://client.crisp.chat"],
+  },
+  tawk: {
+    "script-src": ["https://embed.tawk.to", "https://*.tawk.to"],
+    "connect-src": ["https://*.tawk.to", "wss://*.tawk.to"],
+    "frame-src": ["https://*.tawk.to"],
+    "style-src": ["https://embed.tawk.to"],
+    "img-src": ["https://*.tawk.to", "https://*.tawkcdn.com"],
+    "font-src": ["https://embed.tawk.to"],
+    "media-src": ["https://*.tawkcdn.com"],
+  },
+  zendesk: {
+    "script-src": ["https://static.zdassets.com", "https://ekr.zdassets.com"],
+    "connect-src": [
+      "https://*.zendesk.com",
+      "https://*.zopim.com",
+      "https://ekr.zdassets.com",
+      "https://static.zdassets.com",
+      "wss://widget-mediator.zopim.com",
+      "wss://*.zopim.com",
+    ],
+    "frame-src": ["https://*.zendesk.com", "https://*.zopim.com"],
+    "style-src": ["https://static.zdassets.com"],
+    "img-src": ["https://*.zdassets.com", "https://*.zendesk.com", "https://*.zopim.com"],
+    "font-src": ["https://static.zdassets.com"],
+    "media-src": ["https://*.zendesk.com"],
+  },
+  hubspot: {
+    "script-src": [
+      "https://js.hs-scripts.com",
+      "https://js-eu1.hs-scripts.com",
+      "https://js.hs-analytics.net",
+      "https://js.hs-banner.com",
+      "https://js.usemessages.com",
+      "https://js.hsforms.net",
+      "https://js.hs-scripts.com",
+      "https://js.hubspot.com",
+    ],
+    "connect-src": [
+      "https://*.hubspot.com",
+      "https://*.hubapi.com",
+      "https://*.hs-analytics.net",
+      "https://api.hubspot.com",
+      "https://api.hubapi.com",
+      "wss://*.hubspot.com",
+    ],
+    "frame-src": ["https://app.hubspot.com", "https://*.hubspot.com"],
+    "style-src": ["https://*.hubspot.com", "https://*.hsforms.net"],
+    "img-src": ["https://*.hubspot.com", "https://*.hs-analytics.net", "https://track.hubspot.com"],
+    "font-src": ["https://*.hubspot.com", "https://fonts.hubspot.com"],
+    "media-src": ["https://*.hubspot.com"],
+  },
+  chatwoot: {
+    "script-src": [],
+    "connect-src": [],
+    "frame-src": [],
+    "style-src": [],
+    "img-src": [],
+    "font-src": [],
+    "media-src": [],
+  },
+};
+
+export interface CspOptions {
+  /** Include 'self' in each directive. Default: true. */
+  includeSelf?: boolean;
+  /** Override Chatwoot host for self-hosted directives. */
+  chatwootBaseUrl?: string;
+}
+
+export function cspDirectives(provider: ProviderName, options?: CspOptions): CspDirectives {
+  const includeSelf = options?.includeSelf ?? true;
+  const base = CATALOG[provider] ?? EMPTY;
+
+  if (provider === "chatwoot") {
+    const baseUrl = options?.chatwootBaseUrl?.replace(/\/+$/, "") ?? "https://app.chatwoot.com";
+    const host = new URL(baseUrl).host;
+    const wss = `wss://${host}/cable`;
+    const directives: CspDirectives = {
+      "script-src": [baseUrl],
+      "connect-src": [baseUrl, wss],
+      "frame-src": [baseUrl],
+      "style-src": [baseUrl],
+      "img-src": [baseUrl],
+      "font-src": [baseUrl],
+      "media-src": [baseUrl],
+    };
+    return withSelf(directives, includeSelf);
+  }
+
+  return withSelf(base, includeSelf);
+}
+
+function withSelf(directives: CspDirectives, includeSelf: boolean): CspDirectives {
+  if (!includeSelf) return directives;
+  const out = {} as CspDirectives;
+  for (const key of Object.keys(directives) as CspDirectiveKey[]) {
+    out[key] = ["'self'", ...directives[key]];
+  }
+  return out;
+}
+
+export function toHeaderString(directives: CspDirectives): string {
+  const parts: string[] = [];
+  for (const key of Object.keys(directives) as CspDirectiveKey[]) {
+    const values = directives[key];
+    if (values.length > 0) parts.push(`${key} ${values.join(" ")}`);
+  }
+  return parts.join("; ");
+}
+
+export function mergeCsp(...sets: CspDirectives[]): CspDirectives {
+  const out = {} as CspDirectives;
+  const allKeys: CspDirectiveKey[] = [
+    "script-src",
+    "connect-src",
+    "frame-src",
+    "style-src",
+    "img-src",
+    "font-src",
+    "media-src",
+  ];
+  for (const key of allKeys) {
+    const merged = new Set<string>();
+    for (const set of sets) for (const v of set[key]) merged.add(v);
+    out[key] = [...merged];
+  }
+  return out;
+}
+
+export function watchCspViolations(
+  handler: (event: SecurityPolicyViolationEvent) => void,
+): () => void {
+  if (typeof window === "undefined") return () => {};
+  const cast = handler as () => void;
+  window.addEventListener?.("securitypolicyviolation", cast);
+  return () => window?.removeEventListener?.("securitypolicyviolation", cast);
+}
+
+interface SecurityPolicyViolationEvent {
+  blockedURI: string;
+  violatedDirective: string;
+  effectiveDirective: string;
+  originalPolicy: string;
+}

src/index.ts

@@ -1,6 +1,7 @@
 export { AhizeError, ProviderNotLoadedError, ScriptLoadError } from "./errors.ts";
 export type {
   BaseLoadOptions,
+  DeferStrategy,
   EventMetadata,
   Identity,
   IdentityListener,
@@ -23,5 +24,15 @@ export {
   type LifecycleListener,
   type LifecycleState,
 } from "./_lifecycle.ts";
+export { waitForDefer } from "./_defer.ts";
+export {
+  cspDirectives,
+  mergeCsp,
+  toHeaderString,
+  watchCspViolations,
+  type CspDirectiveKey,
+  type CspDirectives,
+  type CspOptions,
+} from "./csp.ts";
 
 export const version = "0.0.1";

src/providers/chatwoot.ts

@@ -1,3 +1,4 @@
+import { waitForDefer } from "../_defer.ts";
 import { createIdentityStore } from "../_identity.ts";
 import { createLifecycle, hashConfig } from "../_lifecycle.ts";
 import { injectScript, isBrowser, removeScript } from "../_loader.ts";
@@ -59,6 +60,7 @@ export interface ChatwootLoadOptions extends LoadOptions {
 
 export async function load(options: ChatwootLoadOptions): Promise<void> {
   if (!isBrowser()) return;
+  if (options.consent === false) return;
   const baseUrl = normalizeBaseUrl(options.baseUrl ?? "https://app.chatwoot.com");
   const h = hashConfig({ websiteToken: options.websiteToken, baseUrl });
   if (lifecycle.state() === "ready" && lifecycle.configHash() === h) return;
@@ -68,6 +70,7 @@ export async function load(options: ChatwootLoadOptions): Promise<void> {
   lifecycle.setConfigHash(h);
   currentToken = options.websiteToken;
   currentBaseUrl = baseUrl;
+  await waitForDefer(options.defer ?? "immediate");
   if (options.settings) w().chatwootSettings = options.settings;
 
   readyListener = () => {

src/providers/crisp.ts

@@ -1,3 +1,4 @@
+import { waitForDefer } from "../_defer.ts";
 import { createIdentityStore } from "../_identity.ts";
 import { createLifecycle, hashConfig } from "../_lifecycle.ts";
 import { injectScript, isBrowser, removeScript } from "../_loader.ts";
@@ -43,12 +44,14 @@ export interface CrispLoadOptions extends LoadOptions {
 
 export async function load(options: CrispLoadOptions): Promise<void> {
   if (!isBrowser()) return;
+  if (options.consent === false) return;
   const h = hashConfig({ websiteId: options.websiteId, tokenId: options.tokenId });
   if (lifecycle.state() === "ready" && lifecycle.configHash() === h) return;
   if (lifecycle.configHash() && lifecycle.configHash() !== h) await destroy();
 
   lifecycle.transition("loading");
   lifecycle.setConfigHash(h);
+  await waitForDefer(options.defer ?? "immediate");
   bus();
   w().CRISP_WEBSITE_ID = options.websiteId;
   if (options.tokenId) w().CRISP_TOKEN_ID = options.tokenId;

src/providers/hubspot.ts

@@ -1,3 +1,4 @@
+import { waitForDefer } from "../_defer.ts";
 import { createIdentityStore } from "../_identity.ts";
 import { createLifecycle, hashConfig } from "../_lifecycle.ts";
 import { injectScript, isBrowser, removeScript } from "../_loader.ts";
@@ -57,12 +58,14 @@ function lowercaseKeys<T extends Record<string, unknown>>(obj: T): Record<string
 
 export async function load(options: HubSpotLoadOptions): Promise<void> {
   if (!isBrowser()) return;
+  if (options.consent === false) return;
   const h = hashConfig({ portalId: options.portalId, region: options.region });
   if (lifecycle.state() === "ready" && lifecycle.configHash() === h) return;
   if (lifecycle.configHash() && lifecycle.configHash() !== h) await destroy();
 
   lifecycle.transition("loading");
   lifecycle.setConfigHash(h);
+  await waitForDefer(options.defer ?? "immediate");
 
   w().hsConversationsSettings = { loadImmediately: false };
 

src/providers/intercom.ts

@@ -1,3 +1,4 @@
+import { waitForDefer } from "../_defer.ts";
 import { createIdentityStore } from "../_identity.ts";
 import { createLifecycle, hashConfig } from "../_lifecycle.ts";
 import { injectScript, isBrowser, removeScript } from "../_loader.ts";
@@ -50,6 +51,7 @@ export interface IntercomLoadOptions extends LoadOptions {
 
 export async function load(options: IntercomLoadOptions): Promise<void> {
   if (!isBrowser()) return;
+  if (options.consent === false) return;
   const configHash = hashConfig({ appId: options.appId });
   if (lifecycle.state() === "ready" && lifecycle.configHash() === configHash) return;
   if (lifecycle.state() === "loading") return;
@@ -60,6 +62,7 @@ export async function load(options: IntercomLoadOptions): Promise<void> {
   lifecycle.transition("loading");
   currentAppId = options.appId;
   lifecycle.setConfigHash(configHash);
+  await waitForDefer(options.defer ?? "immediate");
   w().intercomSettings = { app_id: options.appId };
   const stub = ensureStub();
   stub("boot", { app_id: options.appId });