@peax/consent-core 0.6.0

package/dist/enforcement/markup.js

@@ -0,0 +1,300 @@
+import { t as requireConsent } from "../validate-D16G7mdG.js";
+import { t as createConsentScript } from "../createConsentScript-C_4ecSTX.js";
+import { t as createConsentIframe } from "../createConsentIframe-Bw-cl--m.js";
+//#region src/enforcement/markup/createConsentMarkupGuard.ts
+var selector = "script[data-peax-use-id],script[data-peax-src],iframe[data-peax-use-id],iframe[data-peax-src]";
+/**
+* Every attribute the guard observes, in one table. The observer filter, the change signature and
+* the option readers all derive from it, and `read` accepts only these keys, so an attribute cannot
+* be read without also being watched and compared.
+*/
+var attributes = {
+	useId: "data-peax-use-id",
+	markerSrc: "data-peax-src",
+	scriptType: "data-peax-script-type",
+	async: "data-peax-async",
+	liveSrc: "src",
+	srcdoc: "srcdoc",
+	textType: "type",
+	nonce: "nonce",
+	integrity: "integrity",
+	crossOrigin: "crossorigin",
+	referrerPolicy: "referrerpolicy",
+	title: "title",
+	sandbox: "sandbox",
+	allow: "allow",
+	loading: "loading",
+	width: "width",
+	height: "height"
+};
+var attributeKeys = Object.keys(attributes);
+var attributeNames = Object.values(attributes);
+function isTemplate(value) {
+	return value.localName === "script" || value.localName === "iframe";
+}
+/** Reads one observed attribute. Absent attributes are undefined so options and signatures agree. */
+function read(template, key) {
+	return template.getAttribute(attributes[key]) ?? void 0;
+}
+/** Framework-neutral, opt-in management of inert marked nodes only. */
+function createConsentMarkupGuard({ consent, root, onIssue }) {
+	requireConsent(consent);
+	if (!root || root.nodeType !== 9 && root.nodeType !== 1) throw new TypeError("Expected a document or element root.");
+	if (onIssue !== void 0 && typeof onIssue !== "function") throw new TypeError("Expected an issue callback.");
+	const document = root.nodeType === 9 ? root : root.ownerDocument;
+	const managed = /* @__PURE__ */ new Map();
+	const invalid = /* @__PURE__ */ new WeakMap();
+	const insertedScripts = /* @__PURE__ */ new WeakSet();
+	const reloadRequired = /* @__PURE__ */ new Set();
+	const listeners = /* @__PURE__ */ new Set();
+	let started = false;
+	let disposed = false;
+	let observer;
+	let unsubscribe;
+	function report(template, reason, error) {
+		onIssue?.(Object.freeze({
+			element: template,
+			reason,
+			error
+		}));
+	}
+	function reportInvalidMarker(template, currentSignature, error) {
+		if (invalid.get(template) === currentSignature) return;
+		invalid.set(template, currentSignature);
+		report(template, "invalid-marker", error);
+	}
+	function attempt(action, failures) {
+		try {
+			action();
+		} catch (error) {
+			failures.push(error);
+		}
+	}
+	function finish(failures) {
+		if (failures.length) throw new AggregateError(failures, "Markup lifecycle failed after cleanup.");
+	}
+	function requireReload(useId, failures) {
+		if (reloadRequired.has(useId)) return;
+		reloadRequired.add(useId);
+		for (const listener of [...listeners]) if (listeners.has(listener)) attempt(listener, failures);
+	}
+	function drop(entry, failures) {
+		managed.delete(entry.template);
+		if (entry.kind === "script" && entry.inserted) requireReload(entry.useId, failures);
+		attempt(() => entry.handle?.remove(), failures);
+		attempt(() => entry.guard.dispose(), failures);
+	}
+	function readMarker(template) {
+		const useId = read(template, "useId");
+		const src = read(template, "markerSrc");
+		if (!useId?.trim() || !src?.trim() || read(template, "liveSrc") !== void 0 || read(template, "srcdoc") !== void 0) throw new TypeError("Marked resource requires a use ID and data-peax-src, without a live src or srcdoc.");
+		if (template.localName === "script" && (read(template, "textType") !== "text/plain" || template.textContent?.trim())) throw new TypeError("Marked external scripts require type=\"text/plain\" and no inline code.");
+		return {
+			useId,
+			src,
+			kind: template.localName
+		};
+	}
+	function signature(template) {
+		return JSON.stringify([...attributeKeys.map((key) => read(template, key) ?? null), template.localName === "script" ? template.textContent : null]);
+	}
+	function mount(entry) {
+		if (entry.handle || entry.kind === "script" && (entry.inserted || insertedScripts.has(entry.template) || reloadRequired.has(entry.useId))) return;
+		if (!consent.evaluate(entry.useId).allowed) return;
+		const parent = entry.template.parentElement;
+		if (!parent?.isConnected) return;
+		try {
+			if (entry.kind === "script") {
+				const template = entry.template;
+				const asyncValue = read(template, "async");
+				if (asyncValue !== void 0 && asyncValue !== "true" && asyncValue !== "false") throw new TypeError("Invalid data-peax-async value.");
+				const { nonce, integrity, crossOrigin, referrerPolicy } = {
+					nonce: read(template, "nonce"),
+					integrity: read(template, "integrity"),
+					crossOrigin: read(template, "crossOrigin"),
+					referrerPolicy: read(template, "referrerPolicy")
+				};
+				const options = {
+					src: entry.src,
+					parent,
+					type: read(template, "scriptType") ?? "classic",
+					async: asyncValue === void 0 ? true : asyncValue === "true",
+					...nonce === void 0 ? {} : { nonce },
+					...integrity === void 0 ? {} : { integrity },
+					...crossOrigin === void 0 ? {} : { crossOrigin },
+					...referrerPolicy === void 0 ? {} : { referrerPolicy }
+				};
+				const handle = entry.guard.load(options);
+				entry.handle = handle;
+				entry.inserted = true;
+				insertedScripts.add(template);
+				handle.ready.catch((error) => {
+					if (managed.get(entry.template) !== entry) return;
+					if (error?.reason === "load-error") report(entry.template, "load-error", error);
+				});
+			} else {
+				const template = entry.template;
+				const { title, sandbox, allow, referrerPolicy, loading, width, height } = {
+					title: read(template, "title") ?? "",
+					sandbox: read(template, "sandbox"),
+					allow: read(template, "allow"),
+					referrerPolicy: read(template, "referrerPolicy"),
+					loading: read(template, "loading"),
+					width: read(template, "width"),
+					height: read(template, "height")
+				};
+				const options = {
+					parent,
+					src: entry.src,
+					title,
+					...sandbox === void 0 ? {} : { sandbox },
+					...allow === void 0 ? {} : { allow },
+					...referrerPolicy === void 0 ? {} : { referrerPolicy },
+					...loading === void 0 ? {} : { loading },
+					...width === void 0 ? {} : { width },
+					...height === void 0 ? {} : { height }
+				};
+				entry.handle = entry.guard.mount(options);
+				entry.inserted = true;
+			}
+			invalid.delete(entry.template);
+		} catch (error) {
+			reportInvalidMarker(entry.template, signature(entry.template), error);
+		}
+	}
+	function reconcile(entry, failures) {
+		if (!consent.evaluate(entry.useId).allowed) {
+			if (entry.handle) {
+				if (entry.kind === "script") requireReload(entry.useId, failures);
+				const handle = entry.handle;
+				entry.handle = void 0;
+				attempt(() => handle.remove(), failures);
+			}
+			return;
+		}
+		mount(entry);
+	}
+	function observeTemplate(template, failures) {
+		if (!template.isConnected || !root.contains(template)) return;
+		const currentSignature = signature(template);
+		let marker;
+		try {
+			marker = readMarker(template);
+		} catch (error) {
+			const previous = managed.get(template);
+			if (previous) drop(previous, failures);
+			reportInvalidMarker(template, currentSignature, error);
+			return;
+		}
+		if (invalid.get(template) !== currentSignature) invalid.delete(template);
+		const previous = managed.get(template);
+		if (previous && previous.signature === currentSignature) {
+			reconcile(previous, failures);
+			return;
+		}
+		if (previous) drop(previous, failures);
+		const guard = marker.kind === "script" ? createConsentScript({
+			consent,
+			useId: marker.useId
+		}) : createConsentIframe({
+			consent,
+			useId: marker.useId
+		});
+		const entry = {
+			template,
+			...marker,
+			signature: currentSignature,
+			guard,
+			inserted: false,
+			handle: void 0
+		};
+		managed.set(template, entry);
+		reconcile(entry, failures);
+	}
+	function scanNode(node, failures) {
+		if (node.nodeType !== 1) return;
+		const element = node;
+		if (isTemplate(element) && element.matches(selector)) observeTemplate(element, failures);
+		for (const candidate of element.querySelectorAll(selector)) if (isTemplate(candidate)) observeTemplate(candidate, failures);
+	}
+	function scan(failures) {
+		if (root.nodeType === 1) scanNode(root, failures);
+		else for (const candidate of root.querySelectorAll(selector)) if (isTemplate(candidate)) observeTemplate(candidate, failures);
+	}
+	function pruneRemoved(failures) {
+		for (const entry of [...managed.values()]) if (!entry.template.isConnected || !root.contains(entry.template)) drop(entry, failures);
+	}
+	return Object.freeze({
+		start() {
+			if (disposed) throw new Error("Markup guard is disposed.");
+			if (started) return;
+			const Observer = document.defaultView?.MutationObserver;
+			if (!Observer) throw new TypeError("Markup guard requires a browser MutationObserver.");
+			started = true;
+			try {
+				unsubscribe = consent.subscribe(() => {
+					const failures = [];
+					for (const entry of [...managed.values()]) attempt(() => reconcile(entry, failures), failures);
+					finish(failures);
+				});
+				observer = new Observer((records) => {
+					const failures = [];
+					const changed = /* @__PURE__ */ new Set();
+					let removed = false;
+					for (const record of records) if (record.type === "childList") {
+						for (const node of record.addedNodes) attempt(() => scanNode(node, failures), failures);
+						if (record.removedNodes.length) removed = true;
+						const target = record.target;
+						if (target.nodeType === 1 && isTemplate(target) && managed.has(target)) changed.add(target);
+					} else {
+						const target = record.type === "characterData" ? record.target.parentElement : record.target;
+						if (target?.nodeType === 1 && isTemplate(target) && (target.matches(selector) || managed.has(target))) changed.add(target);
+					}
+					for (const template of changed) attempt(() => observeTemplate(template, failures), failures);
+					if (removed) pruneRemoved(failures);
+					finish(failures);
+				});
+				observer.observe(root, {
+					subtree: true,
+					childList: true,
+					attributes: true,
+					characterData: true,
+					attributeFilter: attributeNames
+				});
+				const failures = [];
+				scan(failures);
+				finish(failures);
+			} catch (error) {
+				const failures = [];
+				attempt(() => observer?.disconnect(), failures);
+				observer = void 0;
+				attempt(() => unsubscribe?.(), failures);
+				unsubscribe = void 0;
+				for (const entry of [...managed.values()]) drop(entry, failures);
+				started = false;
+				throw error;
+			}
+		},
+		getReloadRequiredUseIds: () => Object.freeze([...reloadRequired]),
+		subscribe(listener) {
+			if (typeof listener !== "function") throw new TypeError("Expected a reload listener.");
+			if (disposed) return () => {};
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			const failures = [];
+			attempt(() => observer?.disconnect(), failures);
+			attempt(() => unsubscribe?.(), failures);
+			for (const entry of [...managed.values()]) drop(entry, failures);
+			listeners.clear();
+			finish(failures);
+		}
+	});
+}
+//#endregion
+export { createConsentMarkupGuard };

package/dist/enforcement/posthog.d.ts

@@ -0,0 +1,68 @@
+declare type Common = Readonly<{
+    id: string;
+    useId: string;
+}>;
+
+declare type ConsentIntegrationActivation = Readonly<{
+    /** Called when consent stops allowing this use or the manager is disposed. */
+    deactivate: (reason: IntegrationDeactivationReason) => void | Promise<void>;
+    /** Executed code cannot be undone; a fresh page is required after deactivation. */
+    reloadOnDeactivate?: boolean;
+}>;
+
+declare type ConsentIntegrationDefinition = Readonly<{
+    id: string;
+    useId: string;
+    activate: (signal: AbortSignal) => ConsentIntegrationActivation | Promise<ConsentIntegrationActivation>;
+    /** Optional bridge for an SDK the application initialized before this manager started. */
+    onBlocked?: () => void;
+    /** Conservatively require a reload if activation fails after partial SDK initialization. */
+    reloadOnError?: boolean;
+}>;
+
+/** One configured capture activity per SDK instance; never partitions one client by multiple uses. */
+export declare function createPostHogIntegration(options: PostHogIntegrationOptions): PostHogIntegration;
+
+declare type IntegrationDeactivationReason = 'blocked' | 'disposed';
+
+/** The small part of posthog-js used by this adapter; posthog-js is app-owned. */
+export declare type PostHogClient = Readonly<{
+    init: (token: string, config: PostHogStrictConfig) => unknown;
+    opt_in_capturing: (options?: {
+        captureEventName: false;
+    }) => unknown;
+    opt_out_capturing: () => unknown;
+    stopSessionRecording?: () => unknown;
+}>;
+
+export declare type PostHogIntegration = ConsentIntegrationDefinition & Readonly<{
+    /** Available after strict activation; existing-sdk mode returns its supplied client. */
+    getClient: () => PostHogClient | undefined;
+}>;
+
+export declare type PostHogIntegrationOptions = (Common & Readonly<{
+    mode?: 'strict';
+    token: string;
+    apiHost?: string;
+    /** Dynamically import the SDK here; nothing is loaded until consent is granted. */
+    loadClient: () => PostHogClient | Promise<PostHogClient>;
+}>) | (Common & Readonly<{
+    mode: 'existing-sdk';
+    /** Already initialized by the app; pre-consent activity cannot be prevented retroactively. */
+    client: PostHogClient;
+}>);
+
+export declare type PostHogStrictConfig = Readonly<{
+    api_host?: string;
+    autocapture: false;
+    capture_pageview: false;
+    capture_pageleave: false;
+    disable_session_recording: true;
+    disable_external_dependency_loading: true;
+    advanced_disable_flags: true;
+    disable_surveys_automatic_display: true;
+    disable_web_experiments: true;
+    opt_out_capturing_by_default: true;
+}>;
+
+export { }

package/dist/enforcement/posthog.js

@@ -0,0 +1,96 @@
+//#region src/enforcement/providers/posthog/createPostHogIntegration.ts
+function disable(client) {
+	let failure;
+	try {
+		client.opt_out_capturing();
+	} catch (error) {
+		failure = error;
+	}
+	try {
+		client.stopSessionRecording?.();
+	} catch (error) {
+		failure ??= error;
+	}
+	if (failure !== void 0) throw failure;
+}
+/** One configured capture activity per SDK instance; never partitions one client by multiple uses. */
+function createPostHogIntegration(options) {
+	if (!options || typeof options.id !== "string" || !options.id.trim() || typeof options.useId !== "string" || !options.useId.trim()) throw new TypeError("Expected non blank integration and use IDs.");
+	if (options.mode === "existing-sdk") {
+		const client = options.client;
+		if (!client || typeof client.opt_in_capturing !== "function" || typeof client.opt_out_capturing !== "function") throw new TypeError("Expected an initialized PostHog client.");
+		return Object.freeze({
+			id: options.id,
+			useId: options.useId,
+			onBlocked: () => disable(client),
+			activate(signal) {
+				if (signal.aborted) return { deactivate: () => {} };
+				client.opt_in_capturing({ captureEventName: false });
+				return {
+					deactivate: () => disable(client),
+					reloadOnDeactivate: true
+				};
+			},
+			getClient: () => client,
+			reloadOnError: true
+		});
+	}
+	if (options.mode !== void 0 && options.mode !== "strict") throw new TypeError("Expected a PostHog integration mode.");
+	if (typeof options.token !== "string" || !options.token.trim() || typeof options.loadClient !== "function") throw new TypeError("Strict PostHog integration requires a token and lazy client loader.");
+	if (options.apiHost !== void 0 && (typeof options.apiHost !== "string" || !options.apiHost.trim())) throw new TypeError("Expected a non blank PostHog API host.");
+	let activeClient;
+	return Object.freeze({
+		id: options.id,
+		useId: options.useId,
+		reloadOnError: true,
+		async activate(signal) {
+			if (signal.aborted) return { deactivate: () => {} };
+			const client = await options.loadClient();
+			if (signal.aborted) return {
+				deactivate: () => {},
+				reloadOnDeactivate: false
+			};
+			if (!client || typeof client.init !== "function" || typeof client.opt_in_capturing !== "function" || typeof client.opt_out_capturing !== "function") throw new TypeError("Expected a PostHog client with init and capture controls.");
+			const config = Object.freeze({
+				...options.apiHost === void 0 ? {} : { api_host: options.apiHost },
+				autocapture: false,
+				capture_pageview: false,
+				capture_pageleave: false,
+				disable_session_recording: true,
+				disable_external_dependency_loading: true,
+				advanced_disable_flags: true,
+				disable_surveys_automatic_display: true,
+				disable_web_experiments: true,
+				opt_out_capturing_by_default: true
+			});
+			try {
+				client.init(options.token, config);
+				if (signal.aborted) {
+					disable(client);
+					return {
+						deactivate: () => disable(client),
+						reloadOnDeactivate: true
+					};
+				}
+				client.opt_in_capturing({ captureEventName: false });
+				activeClient = client;
+				return {
+					deactivate: () => {
+						activeClient = void 0;
+						disable(client);
+					},
+					reloadOnDeactivate: true
+				};
+			} catch (error) {
+				activeClient = void 0;
+				try {
+					disable(client);
+				} catch {}
+				throw error;
+			}
+		},
+		getClient: () => activeClient
+	});
+}
+//#endregion
+export { createPostHogIntegration };