Initial reliable release of consent engine

jurisdiction/resolver.js

@@ -0,0 +1,215 @@
+/**
+ * Universal Cookie Consent
+ * jurisdiction/resolver.js
+ *
+ * Pure deterministic jurisdiction resolver.
+ *
+ * It consumes explicitly supplied signals. It never performs network calls,
+ * reads IP addresses, accesses browser location, or guesses silently.
+ */
+
+import {
+    JURISDICTION_MODES,
+    RESOLUTION_SOURCES,
+    CONFIDENCE_LEVELS,
+    DEFAULT_JURISDICTION_ID,
+    DEFAULT_POLICY_ID,
+    DEFAULT_MODE
+} from "./constants.js";
+import { getJurisdiction, hasJurisdiction } from "./jurisdiction.js";
+import { getPolicy, hasPolicy } from "./policies.js";
+
+const SOURCE_CONFIDENCE = Object.freeze({
+    "site-config": "explicit",
+    server: "high",
+    application: "medium",
+    browser: "low",
+    fallback: "default"
+});
+
+const SOURCE_PRIORITY = Object.freeze({
+    "site-config": 500,
+    server: 400,
+    application: 300,
+    browser: 200,
+    fallback: 100
+});
+
+function isPlainObject(value) {
+    return Boolean(
+        value &&
+        typeof value === "object" &&
+        !Array.isArray(value)
+    );
+}
+
+function normalizeString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+
+function assertMode(mode) {
+    if (!JURISDICTION_MODES.includes(mode)) {
+        throw new TypeError(
+            `Invalid jurisdiction mode. Expected: ${JURISDICTION_MODES.join(", ")}.`
+        );
+    }
+}
+
+function resolveEntry(id, source, status = "resolved") {
+    const entry = getJurisdiction(id);
+
+    if (!entry) {
+        throw new Error(`Unknown jurisdiction: ${id}`);
+    }
+
+    const policy = getPolicy(entry.policy);
+
+    if (!policy) {
+        throw new Error(`Unknown policy: ${entry.policy}`);
+    }
+
+    return Object.freeze({
+        status,
+        jurisdiction: Object.freeze({
+            id: entry.id,
+            country: entry.country,
+            region: entry.region
+        }),
+        policy: Object.freeze({
+            id: policy.id,
+            family: policy.family,
+            version: policy.version
+        }),
+        source,
+        confidence: SOURCE_CONFIDENCE[source]
+    });
+}
+
+function normalizeSignal(signal, fallbackSource) {
+    if (!isPlainObject(signal)) {
+        return null;
+    }
+
+    const id = normalizeString(signal.jurisdiction || signal.id);
+    if (!id || !hasJurisdiction(id)) {
+        return null;
+    }
+
+    const source = normalizeString(signal.source) || fallbackSource;
+    if (!RESOLUTION_SOURCES.includes(source)) {
+        return null;
+    }
+
+    return {
+        id,
+        source,
+        priority: SOURCE_PRIORITY[source]
+    };
+}
+
+function chooseBestSignal(signals) {
+    const candidates = [];
+
+    for (const signal of signals) {
+        const normalized = normalizeSignal(signal, "browser");
+        if (normalized) {
+            candidates.push(normalized);
+        }
+    }
+
+    if (!candidates.length) {
+        return null;
+    }
+
+    candidates.sort((a, b) => b.priority - a.priority);
+    return candidates[0];
+}
+
+function resolveAuto(input) {
+    const site = isPlainObject(input.site) ? input.site : {};
+    const request = isPlainObject(input.request) ? input.request : {};
+    const visitor = isPlainObject(input.visitor) ? input.visitor : {};
+
+    const signal = chooseBestSignal([
+        { jurisdiction: request.jurisdiction, source: request.source || "server" },
+        { jurisdiction: request.regionJurisdiction, source: request.regionSource || "server" },
+        { jurisdiction: visitor.jurisdiction, source: visitor.source || "browser" },
+        { jurisdiction: visitor.regionJurisdiction, source: visitor.regionSource || "browser" },
+        { jurisdiction: site.jurisdiction, source: site.source || "application" }
+    ]);
+
+    if (signal) {
+        return resolveEntry(signal.id, signal.source);
+    }
+
+    return resolveEntry(DEFAULT_JURISDICTION_ID, "fallback", "fallback");
+}
+
+export function resolveJurisdiction(input = {}) {
+    if (!isPlainObject(input)) {
+        throw new TypeError("Jurisdiction input must be an object.");
+    }
+
+    const site = isPlainObject(input.site) ? input.site : {};
+    const mode = normalizeString(input.mode || site.mode || DEFAULT_MODE) || DEFAULT_MODE;
+
+    assertMode(mode);
+
+    if (mode === "global") {
+        return resolveEntry(DEFAULT_JURISDICTION_ID, "site-config");
+    }
+
+    if (mode === "fixed") {
+        const id = normalizeString(input.jurisdiction || site.jurisdiction);
+
+        if (!id) {
+            throw new TypeError(
+                "A jurisdiction is required when mode is \"fixed\"."
+            );
+        }
+
+        if (!hasJurisdiction(id)) {
+            throw new RangeError(`Unknown jurisdiction: ${id}`);
+        }
+
+        return resolveEntry(id, "site-config");
+    }
+
+    return resolveAuto(input);
+}
+
+export function getResolutionPriority(source) {
+    return SOURCE_PRIORITY[source] || 0;
+}
+
+export function getSourceConfidence(source) {
+    return SOURCE_CONFIDENCE[source] || null;
+}
+
+export function isValidResolution(result) {
+    if (!isPlainObject(result)) {
+        return false;
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(result, "status")) {
+        return false;
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(result, "jurisdiction")) {
+        return false;
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(result, "policy")) {
+        return false;
+    }
+
+    return (
+        (result.status === "resolved" || result.status === "fallback") &&
+        typeof result.jurisdiction.id === "string" &&
+        typeof result.policy.id === "string" &&
+        RESOLUTION_SOURCES.includes(result.source) &&
+        CONFIDENCE_LEVELS.includes(result.confidence) &&
+        hasJurisdiction(result.jurisdiction.id) &&
+        hasPolicy(result.policy.id)
+    );
+}