@peax/consent-core 0.6.0

package/dist/storage/sync.d.ts

@@ -0,0 +1,278 @@
+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>>;
+
+/** 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';
+
+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>>;
+
+declare type ConsentStorage = Readonly<{
+    /** Null means no record. Invalid or unreadable records return failure, never empty choices. */
+    load: () => Promise<ConsentStorageResult<ConsentState | null>>;
+    /** Captures validated state at invocation; writes run in invocation order. */
+    save: (state: unknown) => Promise<ConsentStorageResult<void>>;
+    /** Available only when the adapter supports external record invalidation. Does not load or save. */
+    subscribe?: (listener: () => void) => () => void;
+}>;
+
+/** Storage failures deliberately exclude raw errors, URLs, headers, and stored values. */
+declare type ConsentStorageError = Readonly<{
+    type: 'read' | 'write';
+}> | Readonly<{
+    type: 'validation';
+    issues: readonly ValidationIssue[];
+}>;
+
+declare type ConsentStorageResult<T> = Readonly<{
+    success: true;
+    data: T;
+}> | Readonly<{
+    success: false;
+    error: ConsentStorageError;
+}>;
+
+export declare type ConsentSync = Readonly<{
+    /** Claim this runtime, open the channel and refresh. Another started owner returns runtime-in-use. */
+    start: () => Promise<ConsentSyncResult>;
+    /**
+     * Call after saving the exact state object captured from consent.getSnapshot().state.
+     * Clones/revalidated copies and older snapshots broadcast invalidation but do not acknowledge pending choices.
+     * Success confirms sending, not acknowledgment or delivery. Does not save or broadcast choices.
+     */
+    notify: (savedState: ConsentState) => ConsentSyncResult;
+    /** Share same-turn work; later in-flight invalidations require a fresh trailing read before settlement. */
+    refresh: () => Promise<ConsentSyncResult>;
+    getSnapshot: () => ConsentSyncSnapshot;
+    /** Listener failures are contained after commit; registrations remain until unsubscribed or disposed. */
+    subscribe: (listener: () => void) => () => void;
+    /** Close owned listeners/channel; pending storage I/O is not aborted but can no longer apply. */
+    dispose: () => ConsentSyncResult;
+}>;
+
+/** Structural BroadcastChannel contract for application-configured transports and tests. */
+export declare type ConsentSyncChannel = Readonly<{
+    postMessage: (message: unknown) => void;
+    addEventListener: (type: 'message', listener: (event: Readonly<{
+        data: unknown;
+    }>) => void) => void;
+    removeEventListener: (type: 'message', listener: (event: Readonly<{
+        data: unknown;
+    }>) => void) => void;
+    close: () => void;
+}>;
+
+export declare type ConsentSyncError = Readonly<{
+    type: 'channel' | 'read' | 'apply' | 'subscriber' | 'not-started' | 'disposed' | 'runtime-in-use' | 'storage-subscription-unavailable';
+}> | Readonly<{
+    type: 'validation';
+    issues: readonly ValidationIssue[];
+}>;
+
+export declare type ConsentSyncOptions = Readonly<{
+    consent: Pick<ConsentRuntime, 'getSnapshot' | 'restoreState' | 'subscribe'>;
+    /** Pass the complete wrapper; dropping subscribe loses post-cache-update invalidations. */
+    storage: Pick<ConsentStorage, 'load' | 'subscribe'>;
+    /** Scope to the exact application, user and consent record. Not an authentication boundary. */
+    channelName: string;
+    /** Defaults to a lazily constructed native BroadcastChannel at start(). */
+    createChannel?: (name: string) => ConsentSyncChannel;
+    /** Opt in for adapters needing post-cache-update invalidations. start() fails if subscribe is absent. */
+    requireStorageInvalidation?: boolean;
+}>;
+
+export declare type ConsentSyncResult = Readonly<{
+    success: true;
+}> | Readonly<{
+    success: false;
+    error: ConsentSyncError;
+}>;
+
+export declare type ConsentSyncSnapshot = Readonly<{
+    state: 'idle' | 'active' | 'disposed';
+}> | Readonly<{
+    state: 'error';
+    error: ConsentSyncError;
+}>;
+
+/** Synchronize a shared saved record, never policies, user commands or unpersisted choices. */
+export declare function createConsentSync({ consent, storage, channelName, createChannel, requireStorageInvalidation, }: ConsentSyncOptions): ConsentSync;
+
+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/storage/sync.js

@@ -0,0 +1,370 @@
+import { t as assertStorageIdentifier } from "../assertStorageIdentifier-BQuj-9bp.js";
+//#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/storage/sync/createConsentSyncStateTracker.ts
+/** Own choice provenance only; the synchronizer owns I/O revisions and listener lifecycle. */
+function createConsentSyncStateTracker(consent) {
+	let pending = false;
+	let restoring = false;
+	let observedState = consent.getSnapshot().state;
+	return {
+		observeLocalChange() {
+			const current = consent.getSnapshot().state;
+			if (!restoring && current !== observedState) pending = true;
+			observedState = current;
+		},
+		hasPendingChange: () => pending,
+		shouldApplyAfterRead: (before) => !pending && consent.getSnapshot().state === before,
+		acknowledge(savedState) {
+			if (savedState !== consent.getSnapshot().state) return false;
+			pending = false;
+			return true;
+		},
+		restore(state) {
+			restoring = true;
+			try {
+				const result = consent.restoreState(state);
+				const latest = consent.getSnapshot().state;
+				if (result.success && latest !== result.data.state) pending = true;
+				observedState = latest;
+				return result;
+			} catch (error) {
+				const latest = consent.getSnapshot().state;
+				if (!areConsentStatesEqual(latest, state)) pending = true;
+				observedState = latest;
+				throw error;
+			} finally {
+				restoring = false;
+			}
+		}
+	};
+}
+//#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/storage/sync/createSyncStatus.ts
+var success$1 = Object.freeze({ success: true });
+/** Status observers must not turn a background refresh into an unhandled rejection. */
+function createSyncStatus() {
+	let snapshot = Object.freeze({ state: "idle" });
+	let disposed = false;
+	const subscriptions = createConsentSubscription();
+	const unsubscribes = /* @__PURE__ */ new Set();
+	return {
+		getSnapshot: () => snapshot,
+		subscribe(listener) {
+			if (typeof listener !== "function") throw new TypeError("Expected a subscription listener.");
+			if (disposed) return () => {};
+			const remove = subscriptions.subscribe(listener);
+			const unsubscribe = () => {
+				remove();
+				unsubscribes.delete(unsubscribe);
+			};
+			unsubscribes.add(unsubscribe);
+			return unsubscribe;
+		},
+		set(next) {
+			if (disposed) return {
+				success: false,
+				error: { type: "disposed" }
+			};
+			if (snapshot.state === next.state && next.state !== "error") return success$1;
+			snapshot = Object.freeze(next);
+			try {
+				subscriptions.notify();
+			} catch {
+				return {
+					success: false,
+					error: next.state === "error" ? next.error : Object.freeze({ type: "subscriber" })
+				};
+			}
+			return next.state === "error" ? {
+				success: false,
+				error: next.error
+			} : success$1;
+		},
+		dispose() {
+			disposed = true;
+			for (const unsubscribe of unsubscribes) unsubscribe();
+		}
+	};
+}
+//#endregion
+//#region src/storage/sync/createConsentSync.ts
+var success = Object.freeze({ success: true });
+var notification = Object.freeze({
+	type: "peax-consent-changed",
+	formatVersion: 1
+});
+var owners = /* @__PURE__ */ new WeakMap();
+function isNotification(value) {
+	return typeof value === "object" && value !== null && Object.keys(value).length === 2 && "type" in value && value.type === notification.type && "formatVersion" in value && value.formatVersion === 1;
+}
+/** Synchronize a shared saved record, never policies, user commands or unpersisted choices. */
+function createConsentSync({ consent, storage, channelName, createChannel, requireStorageInvalidation }) {
+	assertStorageIdentifier(channelName, "channel name");
+	if (!consent || typeof consent.getSnapshot !== "function" || typeof consent.restoreState !== "function" || typeof consent.subscribe !== "function") throw new TypeError("Expected a consent runtime with getSnapshot, restoreState and subscribe.");
+	if (!storage || typeof storage.load !== "function") throw new TypeError("Expected consent storage with load.");
+	if (createChannel !== void 0 && typeof createChannel !== "function") throw new TypeError("Expected a channel factory.");
+	if (requireStorageInvalidation !== void 0 && typeof requireStorageInvalidation !== "boolean") throw new TypeError("Expected requireStorageInvalidation to be a boolean.");
+	const status = createSyncStatus();
+	const choices = createConsentSyncStateTracker(consent);
+	let revision = 0;
+	let disposed = false;
+	let wakeTarget;
+	let channel;
+	let startPromise;
+	let refreshPromise;
+	let unsubscribe;
+	let unsubscribeStorage;
+	function releaseOwnership() {
+		if (owners.get(consent) === status) owners.delete(consent);
+	}
+	function detachStorage() {
+		const detach = unsubscribeStorage;
+		unsubscribeStorage = void 0;
+		try {
+			detach?.();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	function fail(error) {
+		if (disposed) return {
+			success: false,
+			error: { type: "disposed" }
+		};
+		return status.set({
+			state: "error",
+			error: Object.freeze(error)
+		});
+	}
+	function failClosed(error) {
+		choices.restore({ choices: [] });
+		return fail(error);
+	}
+	async function read(request) {
+		if (disposed) return {
+			success: false,
+			error: { type: "disposed" }
+		};
+		if (!channel) return {
+			success: false,
+			error: { type: "not-started" }
+		};
+		if (choices.hasPendingChange()) return status.getSnapshot().state === "idle" ? status.set({ state: "active" }) : success;
+		let before;
+		try {
+			before = consent.getSnapshot().state;
+		} catch {
+			return fail({ type: "apply" });
+		}
+		let loaded;
+		try {
+			loaded = await storage.load();
+		} catch {
+			loaded = {
+				success: false,
+				error: { type: "read" }
+			};
+		}
+		if (disposed) return {
+			success: false,
+			error: { type: "disposed" }
+		};
+		try {
+			if (request !== revision || !choices.shouldApplyAfterRead(before)) return success;
+			if (!loaded.success) return failClosed(loaded.error.type === "validation" ? loaded.error : { type: "read" });
+			const restored = choices.restore(loaded.data ?? { choices: [] });
+			if (disposed) return {
+				success: false,
+				error: { type: "disposed" }
+			};
+			if (!restored.success) return failClosed({
+				type: "validation",
+				issues: restored.issues
+			});
+			return status.set({ state: "active" });
+		} catch {
+			return fail({ type: "apply" });
+		}
+	}
+	function refresh() {
+		if (disposed || !channel || choices.hasPendingChange()) return read(revision);
+		revision += 1;
+		refreshPromise ??= Promise.resolve().then(async () => {
+			try {
+				let request;
+				let result;
+				do {
+					request = revision;
+					result = await read(request);
+				} while (!disposed && !choices.hasPendingChange() && request !== revision);
+				return result;
+			} finally {
+				refreshPromise = void 0;
+			}
+		});
+		return refreshPromise;
+	}
+	const received = (event) => {
+		if (isNotification(event.data)) refresh();
+	};
+	const wake = () => {
+		refresh();
+	};
+	return Object.freeze({
+		getSnapshot: status.getSnapshot,
+		subscribe: status.subscribe,
+		refresh,
+		start() {
+			if (disposed) return Promise.resolve({
+				success: false,
+				error: { type: "disposed" }
+			});
+			if (startPromise) return startPromise;
+			if (owners.has(consent)) return Promise.resolve(fail({ type: "runtime-in-use" }));
+			if (requireStorageInvalidation && typeof storage.subscribe !== "function") return Promise.resolve(fail({ type: "storage-subscription-unavailable" }));
+			owners.set(consent, status);
+			try {
+				channel = createChannel ? createChannel(channelName) : new BroadcastChannel(channelName);
+				if (disposed) {
+					channel.close();
+					channel = void 0;
+					return Promise.resolve({
+						success: false,
+						error: { type: "disposed" }
+					});
+				}
+				channel.addEventListener("message", received);
+				choices.observeLocalChange();
+				unsubscribe = consent.subscribe(choices.observeLocalChange);
+				unsubscribeStorage = storage.subscribe?.(wake);
+				if (disposed) {
+					detachStorage();
+					return Promise.resolve({
+						success: false,
+						error: { type: "disposed" }
+					});
+				}
+				wakeTarget = typeof window === "undefined" ? void 0 : window;
+				wakeTarget?.addEventListener("focus", wake);
+				wakeTarget?.addEventListener("pageshow", wake);
+				startPromise = refresh();
+				return startPromise;
+			} catch {
+				try {
+					channel?.removeEventListener("message", received);
+				} catch {}
+				try {
+					channel?.close();
+				} catch {}
+				channel = void 0;
+				releaseOwnership();
+				unsubscribe?.();
+				unsubscribe = void 0;
+				detachStorage();
+				wakeTarget?.removeEventListener("focus", wake);
+				wakeTarget?.removeEventListener("pageshow", wake);
+				return Promise.resolve(fail({ type: "channel" }));
+			}
+		},
+		notify(savedState) {
+			if (disposed) return {
+				success: false,
+				error: { type: "disposed" }
+			};
+			if (!channel) return {
+				success: false,
+				error: { type: "not-started" }
+			};
+			try {
+				channel.postMessage(notification);
+				if (disposed) return {
+					success: false,
+					error: { type: "disposed" }
+				};
+				if (choices.acknowledge(savedState)) refresh();
+				return success;
+			} catch {
+				return fail({ type: "channel" });
+			}
+		},
+		dispose() {
+			if (disposed) return success;
+			disposed = true;
+			revision += 1;
+			releaseOwnership();
+			unsubscribe?.();
+			unsubscribe = void 0;
+			wakeTarget?.removeEventListener("focus", wake);
+			wakeTarget?.removeEventListener("pageshow", wake);
+			let failed = !detachStorage();
+			try {
+				channel?.removeEventListener("message", received);
+			} catch {
+				failed = true;
+			}
+			try {
+				channel?.close();
+			} catch {
+				failed = true;
+			}
+			channel = void 0;
+			const result = status.set({ state: "disposed" });
+			status.dispose();
+			return failed ? {
+				success: false,
+				error: { type: "channel" }
+			} : result;
+		}
+	});
+}
+//#endregion
+export { createConsentSync };