@peax/consent-core 0.6.0

package/dist/createConsentScript-C_4ecSTX.js

@@ -0,0 +1,102 @@
+import { t as ConsentEnforcementError } from "./ConsentEnforcementError-Bn_ayWJI.js";
+import { a as setReferrerPolicy, n as insertGuarded, o as setStringAttribute, r as requireParent, s as sourceUrl, t as createDomGuard } from "./createDomGuard-CuIEC0HP.js";
+//#region src/enforcement/script/ConsentScriptError.ts
+var ConsentScriptError = class extends ConsentEnforcementError {
+	name = "ConsentScriptError";
+	constructor(useId, reason) {
+		super(`Consent script stopped (${reason}).`, useId, reason);
+	}
+};
+//#endregion
+//#region src/enforcement/script/createScriptElement.ts
+function createScriptElement(options) {
+	const { src, parent = globalThis.document?.head, type = "classic", async = true, nonce, integrity, crossOrigin, referrerPolicy } = options;
+	if (!parent) throw new TypeError("Expected a script parent or a browser document head.");
+	requireParent(parent);
+	const url = sourceUrl(src, parent);
+	if (type !== "classic" && type !== "module") throw new TypeError("Expected a classic or module script.");
+	if (typeof async !== "boolean") throw new TypeError("Expected a boolean async option.");
+	if (crossOrigin !== void 0 && crossOrigin !== "anonymous" && crossOrigin !== "use-credentials") throw new TypeError("Expected a valid crossOrigin option.");
+	const element = parent.ownerDocument.createElement("script");
+	element.type = type === "module" ? "module" : "text/javascript";
+	element.async = async;
+	setStringAttribute(element, "nonce", nonce);
+	setStringAttribute(element, "integrity", integrity);
+	setStringAttribute(element, "crossorigin", crossOrigin);
+	setReferrerPolicy(element, referrerPolicy);
+	return {
+		element,
+		parent,
+		url
+	};
+}
+//#endregion
+//#region src/enforcement/script/createConsentScript.ts
+/** External-script insertion guard, not a sandbox or an SDK shutdown mechanism. */
+function createConsentScript({ consent, useId }) {
+	const owner = createDomGuard(consent, useId, (reason) => new ConsentScriptError(useId, reason));
+	return Object.freeze({
+		load(options) {
+			const check = owner.begin();
+			const { element, parent, url } = createScriptElement(options);
+			check();
+			let removed = false;
+			let settled = false;
+			let resolveReady;
+			let rejectReady;
+			const ready = new Promise((resolve, reject) => {
+				resolveReady = resolve;
+				rejectReady = reject;
+			});
+			function detachListeners() {
+				element.removeEventListener("load", loaded);
+				element.removeEventListener("error", failed);
+			}
+			function stop(error) {
+				if (removed) return;
+				removed = true;
+				forget();
+				detachListeners();
+				element.remove();
+				if (!settled) {
+					settled = true;
+					rejectReady(error);
+				}
+			}
+			function loaded() {
+				try {
+					check();
+				} catch (error) {
+					stop(error);
+					return;
+				}
+				if (settled) return;
+				settled = true;
+				detachListeners();
+				resolveReady();
+			}
+			function failed() {
+				stop(new ConsentScriptError(useId, "load-error"));
+			}
+			const forget = owner.track(stop);
+			element.addEventListener("load", loaded);
+			element.addEventListener("error", failed);
+			try {
+				check();
+				insertGuarded(element, parent, url, check);
+			} catch (error) {
+				stop(error);
+				ready.catch(() => {});
+				throw error;
+			}
+			return Object.freeze({
+				element,
+				ready,
+				remove: () => stop(new ConsentScriptError(useId, "removed"))
+			});
+		},
+		dispose: owner.dispose
+	});
+}
+//#endregion
+export { ConsentScriptError as n, createConsentScript as t };

package/dist/createDomGuard-CuIEC0HP.js

@@ -0,0 +1,101 @@
+import { n as requireUseId, t as requireConsent } from "./validate-D16G7mdG.js";
+//#region src/enforcement/dom/elementOptions.ts
+function requireText(value, name) {
+	if (typeof value !== "string" || !value.trim()) throw new TypeError(`Expected a non blank ${name}.`);
+}
+function requireParent(parent) {
+	if (parent?.nodeType !== 1 || parent.namespaceURI !== "http://www.w3.org/1999/xhtml" || !parent.isConnected || !parent.ownerDocument?.defaultView || typeof parent.appendChild !== "function") throw new TypeError("Expected a connected HTML parent in a browser document.");
+}
+function sourceUrl(src, parent) {
+	requireText(src, "source URL");
+	const url = new URL(src, parent.ownerDocument.baseURI);
+	if (url.protocol !== "https:" && url.protocol !== "http:") throw new TypeError("Expected an HTTP(S) source URL.");
+	return url.href;
+}
+function setStringAttribute(element, name, value) {
+	if (value === void 0) return;
+	if (typeof value !== "string") throw new TypeError(`Expected a string ${name}.`);
+	element.setAttribute(name, value);
+}
+function setReferrerPolicy(element, value) {
+	if (value !== void 0 && ![
+		"",
+		"no-referrer",
+		"no-referrer-when-downgrade",
+		"origin",
+		"origin-when-cross-origin",
+		"same-origin",
+		"strict-origin",
+		"strict-origin-when-cross-origin",
+		"unsafe-url"
+	].includes(value)) throw new TypeError("Expected a valid referrer policy.");
+	setStringAttribute(element, "referrerpolicy", value);
+}
+//#endregion
+//#region src/enforcement/dom/createDomGuard.ts
+/** Private ownership plumbing shared only by the two DOM loaders. */
+function createDomGuard(consent, useId, makeError) {
+	requireUseId(useId);
+	requireConsent(consent);
+	let disposed = false;
+	let scope = {};
+	const owned = /* @__PURE__ */ new Set();
+	function invalidate(error) {
+		scope.error = error;
+		scope = {};
+		const previous = [...owned];
+		owned.clear();
+		for (const remove of previous) remove(error);
+	}
+	function assertAllowed() {
+		if (disposed) throw makeError("disposed");
+		const result = consent.evaluate(useId);
+		if (!result.allowed) {
+			const error = makeError(result.reason);
+			invalidate(error);
+			throw error;
+		}
+	}
+	const unsubscribe = consent.subscribe(() => {
+		if (disposed) return;
+		const result = consent.evaluate(useId);
+		if (!result.allowed) invalidate(makeError(result.reason));
+	});
+	return {
+		begin() {
+			assertAllowed();
+			const active = scope;
+			return () => {
+				assertAllowed();
+				if (active.error) throw active.error;
+			};
+		},
+		track(remove) {
+			owned.add(remove);
+			return () => {
+				owned.delete(remove);
+			};
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			unsubscribe();
+			invalidate(makeError("disposed"));
+		}
+	};
+}
+/**
+* Starts navigation and inserts the element, re-checking consent at both boundaries that can run
+* app-supplied code (a Trusted Types `createScriptURL` callback during `src`, mutation observers
+* during `appendChild`) and re-validating the parent in between. Callers apply attributes while the
+* element is still disconnected.
+*/
+function insertGuarded(element, parent, url, check) {
+	element.src = url;
+	requireParent(parent);
+	check();
+	parent.appendChild(element);
+	check();
+}
+//#endregion
+export { setReferrerPolicy as a, requireText as i, insertGuarded as n, setStringAttribute as o, requireParent as r, sourceUrl as s, createDomGuard as t };

package/dist/enforcement/axios.d.ts

@@ -0,0 +1,222 @@
+import { AxiosInstance } from 'axios';
+import * as z from 'zod/mini';
+
+/** Disjoint category/use decisions for one scope actually presented to the user. */
+declare type BatchCommand = z.infer<typeof consentDecisionsCommandSchema>;
+
+/** Records choices only for category members in userConsentedPolicy, not future members. */
+declare type CategoryConsentCommand = z.infer<typeof categoryConsentCommandSchema>;
+
+declare const categoryConsentCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    categoryId: z.ZodMiniString<string>;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+/** Explicit request methods, not a replacement AxiosInstance or a global interceptor. */
+export declare type ConsentAxios = Readonly<Pick<AxiosInstance, 'request' | 'get' | 'delete' | 'head' | 'options' | 'post' | 'put' | 'patch'> & {
+    /** Unsubscribes, cancels outstanding requests/bodies, and permanently closes this guard. */
+    dispose: () => void;
+}>;
+
+/** Pre-dispatch rejection. In-flight Axios cancellation normally uses ERR_CANCELED instead. */
+export declare class ConsentAxiosError extends ConsentEnforcementError<ConsentAxiosErrorReason> {
+    readonly name = "ConsentAxiosError";
+    constructor(useId: string, reason: ConsentAxiosErrorReason);
+}
+
+export declare type ConsentAxiosErrorReason = ConsentDeniedReason | 'disposed';
+
+export declare type ConsentAxiosOptions = Readonly<{
+    consent: Pick<ConsentRuntime, 'evaluate' | 'subscribe'>;
+    useId: string;
+    /** Existing client; its defaults and interceptors are not mutated. */
+    client: AxiosInstance;
+}>;
+
+/** userConsentedPolicy is the scope shown for this decision, including a denial. */
+declare type ConsentDecisionCommand = z.infer<typeof consentDecisionCommandSchema>;
+
+declare const consentDecisionCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    useId: z.ZodMiniString<string>;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+declare type ConsentDecisionsCommand = Readonly<Omit<BatchCommand, 'decisions'> & {
+    decisions: readonly ExclusiveTarget<BatchCommand['decisions'][number]>[];
+}>;
+
+declare const consentDecisionsCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    decisions: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniUnion<readonly [z.ZodMiniReadonly<z.ZodMiniObject<{
+        useId: z.ZodMiniString<string>;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>, z.ZodMiniReadonly<z.ZodMiniObject<{
+        categoryId: z.ZodMiniString<string>;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>]>>>;
+}, z.core.$strict>>;
+
+declare type ConsentDeniedReason = 'unknown-use' | 'undecided' | 'denied' | 'consent-version-mismatch';
+
+/**
+ * Shared shape for enforcement guard errors. Only the concrete classes are public: each subpath
+ * exports exactly one of them, so consumers keep their own `instanceof` and literal `name` type.
+ */
+declare abstract class ConsentEnforcementError<Reason extends string> extends Error {
+    readonly useId: string;
+    readonly reason: Reason;
+    constructor(message: string, useId: string, reason: Reason);
+}
+
+declare type ConsentEvaluation = Readonly<{
+    allowed: true;
+}> | Readonly<{
+    allowed: false;
+    reason: ConsentDeniedReason;
+}>;
+
+declare type ConsentPolicy = z.infer<typeof consentPolicySchema>;
+
+declare const consentPolicySchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        title: z.ZodMiniString<string>;
+        description: z.ZodMiniString<string>;
+    }, z.core.$strict>>>>;
+    uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        serviceId: z.ZodMiniString<string>;
+        categoryId: z.ZodMiniString<string>;
+        purposeId: z.ZodMiniString<string>;
+        consentVersion: z.ZodMiniInt;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+
+/** A current use with no decision or a grant for a different consent version. */
+declare type ConsentRequirement = Readonly<{
+    useId: string;
+    categoryId: string;
+    /** The version required by the current policy for this use. */
+    consentVersion: number;
+    reason: 'undecided' | 'consent-version-mismatch';
+}>;
+
+/** In-memory runtime; methods can be passed as callbacks without binding. */
+declare type ConsentRuntime = Readonly<{
+    getSnapshot: () => ConsentSnapshot;
+    evaluate: (useId: string) => ConsentEvaluation;
+    /** Includes undecided uses and version-mismatched grants, not explicit denials. */
+    getMismatchedConsent: () => readonly ConsentRequirement[];
+    /**
+     * Replace all choices from trusted persistence, preserving unknown uses and recorded versions.
+     * Validation checks structure, not evidence of user consent; use decision methods for new choices.
+     * Does not replace policy, renew versions or perform I/O. Effective changes notify existing guards.
+     */
+    restoreState: (state: unknown) => ValidationResult<ConsentSnapshot>;
+    setConsentDecision: (command: ConsentDecisionCommand) => ValidationResult<ConsentSnapshot>;
+    setCategoryConsent: (command: CategoryConsentCommand) => ValidationResult<ConsentSnapshot>;
+    /** Validates all targets before one commit; observer errors can throw after that commit. */
+    setConsentDecisions: (command: ConsentDecisionsCommand) => ValidationResult<ConsentSnapshot>;
+    updatePolicy: (currentAppPolicy: unknown) => ValidationResult<ConsentSnapshot>;
+    subscribe: (listener: () => void) => () => void;
+}>;
+
+/** One active app policy and recorded choices; not a history of policies shown to users. */
+declare type ConsentSnapshot = Readonly<{
+    currentAppPolicy: ConsentPolicy;
+    state: ConsentState;
+}>;
+
+declare type ConsentState = z.infer<typeof consentStateSchema>;
+
+declare const consentStateSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    choices: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        useId: z.ZodMiniString<string>;
+        consentVersion: z.ZodMiniInt;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+
+/** Guards explicit calls through an existing Axios client; never installs global interceptors. */
+export declare function createConsentAxios({ consent, useId, client }: ConsentAxiosOptions): ConsentAxios;
+
+declare type ExclusiveTarget<T> = T extends {
+    useId: string;
+} ? T & {
+    readonly categoryId?: never;
+} : T & {
+    readonly useId?: never;
+};
+
+/** A validation issue without a copy of the rejected input. */
+declare type ValidationIssue = Readonly<{
+    code: string;
+    path: readonly (string | number)[];
+    message: string;
+}>;
+
+declare type ValidationResult<T> = Readonly<{
+    success: true;
+    data: T;
+}> | Readonly<{
+    success: false;
+    issues: readonly ValidationIssue[];
+}>;
+
+export { }

package/dist/enforcement/axios.js

@@ -0,0 +1,92 @@
+import { t as ConsentEnforcementError } from "../ConsentEnforcementError-Bn_ayWJI.js";
+import { n as retainSignal, t as createConsentRequestScope } from "../createConsentRequestScope-D7U8uK6m.js";
+import { n as requireUseId, t as requireConsent } from "../validate-D16G7mdG.js";
+//#region src/enforcement/axios/ConsentAxiosError.ts
+/** Pre-dispatch rejection. In-flight Axios cancellation normally uses ERR_CANCELED instead. */
+var ConsentAxiosError = class extends ConsentEnforcementError {
+	name = "ConsentAxiosError";
+	constructor(useId, reason) {
+		super(`Consent Axios request blocked (${reason}).`, useId, reason);
+	}
+};
+//#endregion
+//#region src/enforcement/axios/combineAxiosSignal.ts
+/** Axios types also permit partial signal shims; this guard requires native-compatible signals. */
+function combineAxiosSignal(scope, caller) {
+	return caller ? AbortSignal.any([scope, caller]) : scope;
+}
+//#endregion
+//#region src/enforcement/axios/createConsentAxios.ts
+/** Guards explicit calls through an existing Axios client; never installs global interceptors. */
+function createConsentAxios({ consent, useId, client }) {
+	requireUseId(useId);
+	requireConsent(consent);
+	if (!client || typeof client.request !== "function" || !client.defaults) throw new TypeError("Expected an Axios client.");
+	const scope = createConsentRequestScope(consent, useId, (reason) => new ConsentAxiosError(useId, reason));
+	async function dispatch(getConfig) {
+		const grantSignal = scope.begin();
+		const input = { ...getConfig() };
+		const originalAdapter = input.adapter === void 0 ? client.defaults.adapter : input.adapter;
+		const signal = combineAxiosSignal(grantSignal, input.signal === void 0 ? client.defaults.signal : input.signal);
+		const adapter = async (finalConfig) => {
+			const axios = await import("axios");
+			const dispatchSignal = combineAxiosSignal(signal, finalConfig.signal);
+			finalConfig.signal = dispatchSignal;
+			scope.assertAllowed();
+			if (finalConfig.signal.aborted) throw new axios.CanceledError(void 0, finalConfig);
+			finalConfig.cancelToken?.throwIfRequested();
+			const getAdapter = axios.getAdapter;
+			const transport = getAdapter(originalAdapter || axios.default.defaults.adapter, finalConfig);
+			scope.assertAllowed();
+			if (finalConfig.signal.aborted) throw new axios.CanceledError(void 0, finalConfig);
+			const response = await transport(finalConfig);
+			retainSignal(dispatchSignal, response, typeof response.data === "object" ? response.data : void 0);
+			return response;
+		};
+		scope.assertAllowed();
+		return client.request({
+			...input,
+			signal,
+			adapter
+		});
+	}
+	/** `method` and `url` always win over the same keys in the caller's config. */
+	function makeRequest(method, url, config) {
+		return {
+			...config,
+			method,
+			url
+		};
+	}
+	/**
+	* Axios resolves `data` through `valueFromConfig2`, so a method that takes a positional `data`
+	* must replace `config.data` even when that argument is undefined; otherwise a caller's
+	* `config.data` would leak through a request whose body the caller never meant to send. Methods
+	* without a positional argument pass `config.data` through untouched.
+	*/
+	function makeRequestWithData(method, url, config, data) {
+		const input = makeRequest(method, url, config);
+		delete input.data;
+		if (data !== void 0) input.data = data;
+		return input;
+	}
+	function withoutBody(method) {
+		return (url, config) => dispatch(() => makeRequest(method, url, config));
+	}
+	function withBody(method) {
+		return (url, data, config) => dispatch(() => makeRequestWithData(method, url, config, data));
+	}
+	return Object.freeze({
+		request: (config) => dispatch(() => config),
+		get: withoutBody("get"),
+		delete: withoutBody("delete"),
+		head: withoutBody("head"),
+		options: withoutBody("options"),
+		post: withBody("post"),
+		put: withBody("put"),
+		patch: withBody("patch"),
+		dispose: scope.dispose
+	});
+}
+//#endregion
+export { ConsentAxiosError, createConsentAxios };