@peax/consent-core 0.6.0

package/dist/index.js

@@ -0,0 +1,445 @@
+import * as z from "zod/mini";
+//#region src/policy/arePoliciesEqual.ts
+/** Structural equality of validated policies; array order matters, object key order does not. */
+function arePoliciesEqual(first, second) {
+	if (first.purposes.length !== second.purposes.length || first.uses.length !== second.uses.length) return false;
+	if (!first.purposes.every((purpose, index) => {
+		const other = second.purposes[index];
+		return other !== void 0 && purpose.id === other.id && purpose.title === other.title && purpose.description === other.description;
+	})) return false;
+	return first.uses.every((use, index) => {
+		const other = second.uses[index];
+		return other !== void 0 && use.id === other.id && use.serviceId === other.serviceId && use.categoryId === other.categoryId && use.purposeId === other.purposeId && use.consentVersion === other.consentVersion;
+	});
+}
+//#endregion
+//#region src/utils/validation.ts
+var nonemptyStringSchema = /* @__PURE__ */ (() => z.string({ error: "Expected a nonempty string." }).check(z.refine((value) => value.trim().length > 0, { error: "Expected a nonempty string." })))();
+var consentVersionSchema = /* @__PURE__ */ (() => z.int({ error: "Expected a positive safe integer consent version." }).check(z.positive({ error: "Expected a positive safe integer consent version." })))();
+/** Internal adapter: keep Zod errors out of the public result contract. */
+function validateWithSchema(schema, input) {
+	const result = schema.safeParse(input, { error: (issue) => issue.code === "unrecognized_keys" ? `Unexpected fields: ${issue.keys.join(", ")}.` : issue.code === "invalid_type" ? `Expected ${issue.expected}.` : "Invalid consent data." });
+	if (result.success) return {
+		success: true,
+		data: result.data
+	};
+	return {
+		success: false,
+		issues: result.error.issues.map((issue) => ({
+			code: issue.code,
+			path: issue.path.map((segment) => typeof segment === "number" ? segment : String(segment)),
+			message: issue.message
+		}))
+	};
+}
+//#endregion
+//#region src/policy/schemas.ts
+var consentPurposeSchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({
+	id: nonemptyStringSchema,
+	title: nonemptyStringSchema,
+	description: nonemptyStringSchema
+})))();
+var consentUseSchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({
+	id: nonemptyStringSchema,
+	serviceId: nonemptyStringSchema,
+	categoryId: nonemptyStringSchema,
+	purposeId: nonemptyStringSchema,
+	/** Version of this use's consent scope, independent of other uses. */
+	consentVersion: consentVersionSchema
+})))();
+var consentPolicySchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({
+	purposes: z.readonly(z.array(consentPurposeSchema).check((context) => {
+		const ids = /* @__PURE__ */ new Set();
+		context.value.forEach((purpose, index) => {
+			if (ids.has(purpose.id)) context.issues.push({
+				code: "custom",
+				path: [index, "id"],
+				message: "Consent purpose IDs must be unique.",
+				input: purpose.id
+			});
+			ids.add(purpose.id);
+		});
+	})),
+	uses: z.readonly(z.array(consentUseSchema).check((context) => {
+		const ids = /* @__PURE__ */ new Set();
+		context.value.forEach((use, index) => {
+			if (ids.has(use.id)) context.issues.push({
+				code: "custom",
+				path: [index, "id"],
+				message: "Consent use IDs must be unique.",
+				input: use.id
+			});
+			ids.add(use.id);
+		});
+	}))
+}).check((context) => {
+	if (context.issues.length > 0) return;
+	const purposeIds = new Set(context.value.purposes.map((purpose) => purpose.id));
+	context.value.uses.forEach((use, index) => {
+		if (!purposeIds.has(use.purposeId)) context.issues.push({
+			code: "custom",
+			path: [
+				"uses",
+				index,
+				"purposeId"
+			],
+			message: "Consent use must reference a declared purpose.",
+			input: use.purposeId
+		});
+	});
+})))();
+//#endregion
+//#region src/policy/validateConsentPolicy.ts
+/** Validates policy structure, not its approval or the legal adequacy of its purposes. */
+function validateConsentPolicy(input) {
+	return validateWithSchema(consentPolicySchema, input);
+}
+//#endregion
+//#region src/consent/areConsentStatesEqual.ts
+/** Compare recorded choices, not permission or policy compatibility. Choice order is preserved. */
+function areConsentStatesEqual(first, second) {
+	return first.choices.length === second.choices.length && first.choices.every((choice, index) => {
+		const other = second.choices[index];
+		return other?.useId === choice.useId && other.consentVersion === choice.consentVersion && other.decision === choice.decision;
+	});
+}
+//#endregion
+//#region src/consent/createConsentSubscription.ts
+/** Synchronous invalidation notifications, not a log of every intermediate state. */
+function createConsentSubscription() {
+	const listeners = /* @__PURE__ */ new Set();
+	let notifying = false;
+	let pending = false;
+	return {
+		subscribe(listener) {
+			if (typeof listener !== "function") throw new TypeError("Expected a subscription listener.");
+			const subscription = () => listener();
+			listeners.add(subscription);
+			return () => {
+				listeners.delete(subscription);
+			};
+		},
+		notify() {
+			pending = true;
+			if (notifying) return;
+			notifying = true;
+			const errors = [];
+			try {
+				do {
+					pending = false;
+					for (const listener of [...listeners]) {
+						if (!listeners.has(listener)) continue;
+						try {
+							listener();
+						} catch (error) {
+							errors.push(error);
+						}
+					}
+				} while (pending);
+			} finally {
+				notifying = false;
+			}
+			if (errors.length > 0) throw new AggregateError(errors, "Consent subscribers failed after the change was committed.");
+		}
+	};
+}
+//#endregion
+//#region src/consent/evaluateConsent.ts
+/**
+* Evaluates one use without mutating inputs or performing enforcement.
+* Inputs must be validated, with unique policy use IDs and at most one choice
+* per use. Denials remain blocked regardless of their consent version.
+* A version mismatch blocks only this use, not other unchanged uses.
+*/
+function evaluateConsent({ currentAppPolicy, state, useId }) {
+	const use = currentAppPolicy.uses.find((use) => use.id === useId);
+	if (!use) return {
+		allowed: false,
+		reason: "unknown-use"
+	};
+	const choice = state.choices.find((choice) => choice.useId === useId);
+	if (!choice) return {
+		allowed: false,
+		reason: "undecided"
+	};
+	if (choice.decision === "denied") return {
+		allowed: false,
+		reason: "denied"
+	};
+	if (choice.consentVersion !== use.consentVersion) return {
+		allowed: false,
+		reason: "consent-version-mismatch"
+	};
+	return { allowed: true };
+}
+//#endregion
+//#region src/consent/getMismatchedConsent.ts
+/**
+* Lists undecided uses and mismatched grants in policy order, without changing
+* choices or prompting the user. Inputs must follow evaluateConsent's validated
+* input contract. An empty result is not blanket permission: denials are omitted.
+*/
+function getMismatchedConsent({ currentAppPolicy, state }) {
+	return currentAppPolicy.uses.flatMap((use) => {
+		const evaluation = evaluateConsent({
+			currentAppPolicy,
+			state,
+			useId: use.id
+		});
+		if (evaluation.allowed) return [];
+		if (evaluation.reason !== "undecided" && evaluation.reason !== "consent-version-mismatch") return [];
+		return [{
+			useId: use.id,
+			categoryId: use.categoryId,
+			consentVersion: use.consentVersion,
+			reason: evaluation.reason
+		}];
+	});
+}
+//#endregion
+//#region src/consent/schemas.ts
+var consentDecisionSchema = /* @__PURE__ */ z.enum(["granted", "denied"], { error: "Expected granted or denied." });
+var consentChoiceSchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({
+	useId: nonemptyStringSchema,
+	consentVersion: consentVersionSchema,
+	decision: consentDecisionSchema
+})))();
+var consentStateSchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({ choices: z.readonly(z.array(consentChoiceSchema).check((context) => {
+	const ids = /* @__PURE__ */ new Set();
+	context.value.forEach((choice, index) => {
+		if (ids.has(choice.useId)) context.issues.push({
+			code: "custom",
+			path: [index, "useId"],
+			message: "Only one consent choice per use is allowed.",
+			input: choice.useId
+		});
+		ids.add(choice.useId);
+	});
+})) })))();
+var createConsentOptionsSchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({
+	currentAppPolicy: consentPolicySchema,
+	initialState: consentStateSchema
+})))();
+var consentDecisionCommandSchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({
+	userConsentedPolicy: consentPolicySchema,
+	useId: nonemptyStringSchema,
+	decision: consentDecisionSchema
+})))();
+var categoryConsentCommandSchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({
+	userConsentedPolicy: consentPolicySchema,
+	categoryId: nonemptyStringSchema,
+	decision: consentDecisionSchema
+})))();
+var consentDecisionsCommandSchema = /* @__PURE__ */ (() => z.readonly(z.strictObject({
+	userConsentedPolicy: consentPolicySchema,
+	decisions: z.readonly(z.array(z.union([z.readonly(z.strictObject({
+		useId: nonemptyStringSchema,
+		decision: consentDecisionSchema
+	})), z.readonly(z.strictObject({
+		categoryId: nonemptyStringSchema,
+		decision: consentDecisionSchema
+	}))])))
+})))();
+//#endregion
+//#region src/consent/setConsent.ts
+/**
+* Records an explicit decision for every use in a category of the supplied policy.
+* Pass only the policy scope presented to the user; this creates no blanket grant
+* for future uses. Inputs follow the same validation contract as setConsentDecision.
+* Throws when no uses match; returns the same state when all choices are unchanged.
+*/
+function setCategoryConsent({ userConsentedPolicy, state, categoryId, decision }) {
+	const uses = userConsentedPolicy.uses.filter((use) => use.categoryId === categoryId);
+	if (uses.length === 0) throw new Error(`Unknown consent category: ${categoryId}`);
+	return uses.reduce((nextState, use) => setConsentDecision({
+		userConsentedPolicy,
+		decision,
+		state: nextState,
+		useId: use.id
+	}), state);
+}
+/**
+* Records an explicit decision for one use at the supplied policy's version.
+* Pass the policy presented to the user, not a newer policy they have not seen.
+* Inputs must be validated, with unique use IDs and at most one choice per use.
+* Throws for an unknown use; returns the same state for an identical choice.
+*/
+function setConsentDecision({ userConsentedPolicy, state, useId, decision }) {
+	const use = userConsentedPolicy.uses.find((use) => use.id === useId);
+	if (!use) throw new Error(`Unknown consent use: ${useId}`);
+	const previous = state.choices.find((choice) => choice.useId === useId);
+	if (previous?.decision === decision && previous.consentVersion === use.consentVersion) return state;
+	const choice = {
+		useId,
+		consentVersion: use.consentVersion,
+		decision
+	};
+	return { choices: previous ? state.choices.map((existing) => existing.useId === useId ? choice : existing) : [...state.choices, choice] };
+}
+//#endregion
+//#region src/consent/setConsentDecisions.ts
+/** Validated command in, one pure merged state out; no partially applied targets. */
+function setConsentDecisions({ userConsentedPolicy, decisions }, state) {
+	const targets = /* @__PURE__ */ new Set();
+	const selected = /* @__PURE__ */ new Map();
+	const issues = [];
+	decisions.forEach((item, index) => {
+		const field = "useId" in item ? "useId" : "categoryId";
+		const id = "useId" in item ? item.useId : item.categoryId;
+		const path = [
+			"decisions",
+			index,
+			field
+		];
+		const target = `${field}:${id}`;
+		if (targets.has(target)) {
+			issues.push({
+				code: "duplicate_target",
+				path,
+				message: "Duplicate consent target."
+			});
+			return;
+		}
+		targets.add(target);
+		const uses = userConsentedPolicy.uses.filter((use) => field === "useId" ? use.id === id : use.categoryId === id);
+		if (!uses.length) issues.push({
+			code: "unknown_target",
+			path,
+			message: "Unknown consent target."
+		});
+		uses.forEach((use) => {
+			if (selected.has(use.id)) issues.push({
+				code: "overlapping_target",
+				path,
+				message: "Consent targets must not overlap."
+			});
+			else selected.set(use.id, {
+				useId: use.id,
+				consentVersion: use.consentVersion,
+				decision: item.decision
+			});
+		});
+	});
+	if (issues.length) return {
+		success: false,
+		issues
+	};
+	let changed = false;
+	const choices = state.choices.map((previous) => {
+		const next = selected.get(previous.useId);
+		selected.delete(previous.useId);
+		if (!next || next.decision === previous.decision && next.consentVersion === previous.consentVersion) return previous;
+		changed = true;
+		return next;
+	});
+	userConsentedPolicy.uses.forEach((use) => {
+		const choice = selected.get(use.id);
+		if (choice) {
+			choices.push(choice);
+			changed = true;
+		}
+	});
+	return {
+		success: true,
+		data: changed ? { choices } : state
+	};
+}
+//#endregion
+//#region src/consent/createConsent.ts
+function createSnapshot(currentAppPolicy, state) {
+	state.choices.forEach((choice) => {
+		Object.freeze(choice);
+	});
+	Object.freeze(state.choices);
+	Object.freeze(state);
+	return Object.freeze({
+		currentAppPolicy,
+		state
+	});
+}
+function snapshotRequirements(snapshot) {
+	return Object.freeze(getMismatchedConsent(snapshot).map((requirement) => Object.freeze(requirement)));
+}
+/** Creates an isolated runtime from decoded data; invalid input creates no instance. */
+function createConsent(input) {
+	const result = validateWithSchema(createConsentOptionsSchema, input);
+	if (!result.success) return result;
+	let snapshot = createSnapshot(result.data.currentAppPolicy, result.data.initialState);
+	let requirements = snapshotRequirements(snapshot);
+	const subscriptions = createConsentSubscription();
+	function commit(currentAppPolicy, state) {
+		if (snapshot.currentAppPolicy === currentAppPolicy && snapshot.state === state) return {
+			success: true,
+			data: snapshot
+		};
+		const next = createSnapshot(currentAppPolicy, state);
+		const nextRequirements = snapshotRequirements(next);
+		snapshot = next;
+		requirements = nextRequirements;
+		subscriptions.notify();
+		return {
+			success: true,
+			data: next
+		};
+	}
+	return {
+		success: true,
+		data: Object.freeze({
+			getSnapshot: () => snapshot,
+			evaluate: (useId) => evaluateConsent({
+				...snapshot,
+				useId
+			}),
+			getMismatchedConsent: () => requirements,
+			restoreState(input) {
+				const parsed = validateWithSchema(consentStateSchema, input);
+				if (!parsed.success) return parsed;
+				if (areConsentStatesEqual(parsed.data, snapshot.state)) return {
+					success: true,
+					data: snapshot
+				};
+				return commit(snapshot.currentAppPolicy, parsed.data);
+			},
+			setConsentDecision(command) {
+				const parsed = validateWithSchema(consentDecisionCommandSchema, command);
+				if (!parsed.success) return parsed;
+				const { userConsentedPolicy, useId, decision } = parsed.data;
+				return commit(snapshot.currentAppPolicy, setConsentDecision({
+					userConsentedPolicy,
+					state: snapshot.state,
+					useId,
+					decision
+				}));
+			},
+			setCategoryConsent(command) {
+				const parsed = validateWithSchema(categoryConsentCommandSchema, command);
+				if (!parsed.success) return parsed;
+				const { userConsentedPolicy, categoryId, decision } = parsed.data;
+				return commit(snapshot.currentAppPolicy, setCategoryConsent({
+					userConsentedPolicy,
+					state: snapshot.state,
+					categoryId,
+					decision
+				}));
+			},
+			updatePolicy(input) {
+				const parsed = validateConsentPolicy(input);
+				if (!parsed.success) return parsed;
+				if (arePoliciesEqual(parsed.data, snapshot.currentAppPolicy)) return {
+					success: true,
+					data: snapshot
+				};
+				return commit(parsed.data, snapshot.state);
+			},
+			setConsentDecisions(command) {
+				const parsed = validateWithSchema(consentDecisionsCommandSchema, command);
+				if (!parsed.success) return parsed;
+				const result = setConsentDecisions(parsed.data, snapshot.state);
+				return result.success ? commit(snapshot.currentAppPolicy, result.data) : result;
+			},
+			subscribe: subscriptions.subscribe
+		})
+	};
+}
+//#endregion
+export { createConsent };

package/dist/storage/localforage.d.ts

@@ -0,0 +1,23 @@
+/** One record, scoped by the adapter's key or endpoint. Only null means absent. */
+declare type ConsentStorageAdapter = Readonly<{
+    read: () => string | null | Promise<string | null>;
+    write: (record: string) => void | Promise<void>;
+    /** Optional lazy, key-scoped external invalidations; notifications contain no stored values. */
+    subscribe?: (listener: () => void) => () => void;
+}>;
+
+export declare function createLocalForageAdapter({ key, store }: LocalForageAdapterOptions): ConsentStorageAdapter;
+
+export declare type LocalForageAdapterOptions = Readonly<{
+    key: string;
+    /** Supply an existing configured instance, or use the lazy peax-consent/consent store. */
+    store?: LocalForageStore;
+}>;
+
+/** Structural interface keeps optional peer declarations out of the other entry points. */
+export declare type LocalForageStore = Readonly<{
+    getItem: (key: string) => Promise<unknown>;
+    setItem: (key: string, record: string) => Promise<unknown>;
+}>;
+
+export { }

package/dist/storage/localforage.js

@@ -0,0 +1,26 @@
+import { t as assertStorageIdentifier } from "../assertStorageIdentifier-BQuj-9bp.js";
+//#region src/storage/localforage/createLocalForageAdapter.ts
+function createLocalForageAdapter({ key, store }) {
+	assertStorageIdentifier(key);
+	let pendingStore;
+	const getStore = () => {
+		if (store) return Promise.resolve(store);
+		pendingStore ??= import("localforage").then(({ default: localforage }) => localforage.createInstance({
+			name: "peax-consent",
+			storeName: "consent"
+		}));
+		return pendingStore;
+	};
+	return Object.freeze({
+		read: async () => {
+			const record = await (await getStore()).getItem(key);
+			if (record !== null && typeof record !== "string") throw new TypeError("Expected a stored string or null.");
+			return record;
+		},
+		write: async (record) => {
+			await (await getStore()).setItem(key, record);
+		}
+	});
+}
+//#endregion
+export { createLocalForageAdapter };