@devslab/site-kit 0.15.0 → 0.16.0

package/src/core/consent.mjs

@@ -0,0 +1,567 @@
+import { GTM_CONTAINER_ID_PATTERN, gtmHeadScript } from "./gtm.mjs";
+
+/**
+ * Opt-in analytics consent for the family sites (D-034).
+ *
+ * Nothing that contacts Google — the Tag Manager loader, gtag, GA cookies —
+ * runs until the visitor grants analytics for the current policy version.
+ * Without a decision, after "Reject", after a dismissed banner, or under an
+ * older policy version, the page only pushes Consent Mode v2 defaults (all
+ * denied) into its own dataLayer. That push is local; it reaches nobody.
+ *
+ * This file is framework-free and dependency-free: it runs in the source
+ * stage of CI (no packages installed), in Workers, in Node and in browsers.
+ * The DOM is touched only inside a manager's methods, never at import time
+ * or creation, so a manager can be created in shared module scope on a
+ * server that renders many requests.
+ */
+
+export const CONSENT_COOKIE_NAME = "site_consent";
+/** Twelve months. The cookie expires then, and a decision older than this no longer counts. */
+export const CONSENT_MAX_AGE_SECONDS = 365 * 24 * 60 * 60;
+/** Letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 32 characters: "2026-10-05". */
+export const CONSENT_POLICY_VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z._-]{0,31}$/;
+/** 128 random bits as lowercase hex. Not derived from anything about the visitor. */
+export const CONSENT_ANONYMOUS_ID_PATTERN = /^[0-9a-f]{32}$/;
+export const CONSENT_ACTIONS = Object.freeze(["grant", "deny", "withdraw", "update"]);
+/**
+ * Consent Mode v2 defaults: everything denied. There is no advertising
+ * category in the family, so the three ad signals are never updated.
+ */
+export const CONSENT_MODE_DEFAULTS = Object.freeze({
+  ad_personalization: "denied",
+  ad_storage: "denied",
+  ad_user_data: "denied",
+  analytics_storage: "denied",
+});
+/** Cookies Google Analytics writes: `_ga`, `_ga_<stream>`, and the older `_gid` / `_gat*`. */
+export const GA_COOKIE_PATTERN = /^(?:_ga|_gid|_gat)(?:_[0-9A-Za-z_-]+)?$/;
+/**
+ * Headers for every response whose HTML was rendered from the consent cookie
+ * (a TanStack route using `consent`). A granted visitor's head carries the
+ * Tag Manager loader; if a CDN or edge cache stored that page, visitors who
+ * never consented would be served the loader. `private, no-store` keeps it
+ * out of shared caches; `Vary: Cookie` covers a cache that honours it anyway.
+ */
+export const CONSENT_RESPONSE_HEADERS = Object.freeze({ "Cache-Control": "private, no-store", Vary: "Cookie" });
+/** A consent record body is a handful of short fields; anything longer is refused before parsing. */
+export const CONSENT_RECORD_MAX_BYTES = 1024;
+
+const GTM_SCRIPT_PREFIX = "https://www.googletagmanager.com/gtm.js";
+const COOKIE_NAME_PATTERN = /^[0-9A-Za-z_-]{1,64}$/;
+const COOKIE_DOMAIN_PATTERN = /^\.?[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)+$/;
+const MEASUREMENT_ID_PATTERN = /^G-[0-9A-Z]+$/;
+const COOKIE_KEYS = ["a", "id", "t", "v"];
+const RECORD_KEYS = ["action", "analytics", "anonymousId", "decidedAt", "path", "policyVersion", "source"];
+const CLOCK_SKEW_SECONDS = 10 * 60;
+const MAX_PATH_LENGTH = 512;
+const GATE = Symbol.for("@devslab/site-kit/consent-gate");
+
+const fail = (message) => { throw new RangeError(message); };
+const checkVersion = (value) =>
+  typeof value === "string" && CONSENT_POLICY_VERSION_PATTERN.test(value)
+    ? value
+    : fail(`consent policy version must match ${CONSENT_POLICY_VERSION_PATTERN}; got ${JSON.stringify(value)}`);
+const checkCookieName = (value) =>
+  typeof value === "string" && COOKIE_NAME_PATTERN.test(value) ? value : fail(`consent cookie name must match ${COOKIE_NAME_PATTERN}; got ${JSON.stringify(value)}`);
+const checkDomain = (value) =>
+  typeof value === "string" && COOKIE_DOMAIN_PATTERN.test(value) ? value : fail(`consent cookie domain must be a host name; got ${JSON.stringify(value)}`);
+const checkMaxAge = (value) =>
+  Number.isInteger(value) && value > 0 && value <= CONSENT_MAX_AGE_SECONDS ? value : fail(`consent max age must be 1..${CONSENT_MAX_AGE_SECONDS} seconds; got ${JSON.stringify(value)}`);
+const checkGtm = (value) =>
+  typeof value === "string" && GTM_CONTAINER_ID_PATTERN.test(value) ? value : fail(`Google Tag Manager container id must match ${GTM_CONTAINER_ID_PATTERN}; got ${JSON.stringify(value)}`);
+const checkMeasurementId = (value) =>
+  typeof value === "string" && MEASUREMENT_ID_PATTERN.test(value) ? value : fail(`GA4 measurement id must match ${MEASUREMENT_ID_PATTERN}; got ${JSON.stringify(value)}`);
+
+const isConsentState = (state) =>
+  state !== null && typeof state === "object" &&
+  typeof state.v === "string" && CONSENT_POLICY_VERSION_PATTERN.test(state.v) &&
+  (state.a === 0 || state.a === 1) &&
+  Number.isSafeInteger(state.t) && state.t > 0 &&
+  typeof state.id === "string" && CONSENT_ANONYMOUS_ID_PATTERN.test(state.id);
+
+/**
+ * Parses a consent cookie value (`v=<version>&a=<0|1>&t=<unix seconds>&id=<hex>`).
+ * Strict: exactly those four keys, each once and well-formed; anything else is `null`.
+ */
+export function parseConsentCookie(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 256) return null;
+  const pairs = value.split("&").map((pair) => pair.split("="));
+  if (pairs.some((pair) => pair.length !== 2)) return null;
+  const keys = pairs.map(([key]) => key).sort();
+  if (keys.join() !== COOKIE_KEYS.join()) return null;
+  const fields = Object.fromEntries(pairs);
+  if (fields.a !== "0" && fields.a !== "1") return null;
+  if (!/^[1-9][0-9]{0,11}$/.test(fields.t)) return null;
+  const state = { v: fields.v, a: Number(fields.a), t: Number(fields.t), id: fields.id };
+  return isConsentState(state) ? Object.freeze(state) : null;
+}
+
+/** The cookie value for a state. Throws RangeError for a malformed state. */
+export function formatConsentCookie(state) {
+  if (!isConsentState(state)) fail(`not a consent state: ${JSON.stringify(state)}`);
+  return `v=${state.v}&a=${state.a}&t=${state.t}&id=${state.id}`;
+}
+
+/**
+ * The full cookie string for `document.cookie` or a `Set-Cookie` header:
+ * first-party, `Path=/`, `SameSite=Lax`, `Secure`, twelve months. Not
+ * `HttpOnly` — the banner reads it. Host-only unless `domain` is given.
+ */
+export function serializeConsentCookie(state, options = {}) {
+  const name = checkCookieName(options.name ?? CONSENT_COOKIE_NAME);
+  const maxAge = checkMaxAge(options.maxAgeSeconds ?? CONSENT_MAX_AGE_SECONDS);
+  const domain = options.domain === undefined ? "" : `; Domain=${checkDomain(options.domain)}`;
+  return `${name}=${formatConsentCookie(state)}; Path=/; Max-Age=${maxAge}${domain}; SameSite=Lax; Secure`;
+}
+
+/** The first value of `name` in a Cookie header (or `document.cookie`). */
+function cookieValue(header, name) {
+  if (typeof header !== "string") return undefined;
+  for (const part of header.split(";")) {
+    const index = part.indexOf("=");
+    if (index === -1) continue;
+    if (part.slice(0, index).trim() === name) return part.slice(index + 1).trim();
+  }
+  return undefined;
+}
+
+const nowSeconds = (now) => Math.floor((now ?? Date.now()) / 1000);
+
+/**
+ * True when `state` grants analytics for `policyVersion` and is neither older
+ * than the cookie's lifetime nor dated in the future.
+ */
+export function analyticsConsented(state, policyVersion, options = {}) {
+  checkVersion(policyVersion);
+  if (!isConsentState(state) || state.v !== policyVersion || state.a !== 1) return false;
+  return isFresh(state, options);
+}
+
+function isFresh(state, options) {
+  const now = nowSeconds(options.now);
+  const maxAge = checkMaxAge(options.maxAgeSeconds ?? CONSENT_MAX_AGE_SECONDS);
+  return state.t <= now + CLOCK_SKEW_SECONDS && now - state.t <= maxAge;
+}
+
+/**
+ * The visitor's decision for the current policy version, read from a Cookie
+ * header (server) or `document.cookie` (browser): `null` when there is none,
+ * when it is malformed, expired, or made under another policy version. A
+ * `null` means "ask".
+ */
+export function readConsentCookie(cookieHeader, options) {
+  const policyVersion = checkVersion(options?.policyVersion);
+  const state = parseConsentCookie(cookieValue(cookieHeader, checkCookieName(options.cookieName ?? CONSENT_COOKIE_NAME)));
+  if (!state || state.v !== policyVersion || !isFresh(state, options)) return null;
+  return state;
+}
+
+/** Shorthand for "load analytics on this request": a current, fresh grant in the Cookie header. */
+export function consentCookieGrantsAnalytics(cookieHeader, options) {
+  return readConsentCookie(cookieHeader, options)?.a === 1;
+}
+
+const DEFAULTS_JSON = JSON.stringify(CONSENT_MODE_DEFAULTS);
+
+/**
+ * The body of the head `<script>` every page with Tag Manager carries,
+ * without the tag or a nonce (the renderer owns both, as with gtmHeadScript).
+ *
+ * Not granted: Consent Mode defaults pushed into the page's own dataLayer,
+ * nothing else — no Google host appears in the string.
+ * Granted (and a container id given): the same defaults, an update granting
+ * `analytics_storage`, then Google's loader, which is skipped if gtm.js is
+ * already on the page (a client-side navigation re-running the head).
+ * Either way the first copy to run marks the page so later copies do nothing.
+ */
+export function consentHeadScript(options = {}) {
+  const granted = options.granted === true;
+  const gtm = options.gtm === undefined ? undefined : checkGtm(options.gtm);
+  const mode = granted ? "granted" : "denied";
+  const update = granted ? `g("consent","update",{"analytics_storage":"granted"});` : "";
+  const bootstrap = `(function(w){if(w.__siteConsent)return;w.__siteConsent="${mode}";w.dataLayer=w.dataLayer||[];function g(){w.dataLayer.push(arguments)}g("consent","default",${DEFAULTS_JSON});${update}})(window);`;
+  if (!granted || gtm === undefined) return bootstrap;
+  return `${bootstrap}\nif(!document.querySelector('script[src^="${GTM_SCRIPT_PREFIX}"]')){${gtmHeadScript(gtm)}}`;
+}
+
+/**
+ * A page path as it goes into a consent record: the part before any query or
+ * fragment, starting with "/", at most 512 characters. Anything else is "/".
+ */
+export function normalizeConsentPath(path) {
+  if (typeof path !== "string") return "/";
+  const bare = path.split(/[?#]/, 1)[0] ?? "";
+  if (!bare.startsWith("/") || bare.startsWith("//") || bare.length > MAX_PATH_LENGTH || /[\s\0-\x1f\x7f]/.test(bare)) return "/";
+  return bare;
+}
+
+const isPlainObject = (value) => value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
+
+/**
+ * Validates a consent record a browser POSTed (server side). Accepts the JSON
+ * text or the parsed object; returns a frozen record or `null`. Strict: the
+ * exact seven keys, a known policy version (one, or a list while an older
+ * version's pending records drain), an action that agrees with `analytics`,
+ * a normalised path, a `decidedAt` neither in the future nor older than
+ * `maxAgeSeconds` (default 31 days). The server adds who, where from and
+ * when it arrived; nothing here identifies a person.
+ */
+export function parseConsentRecord(input, options) {
+  const versions = [options?.policyVersion].flat().map(checkVersion);
+  let body = input;
+  if (typeof input === "string") {
+    if (input.length > CONSENT_RECORD_MAX_BYTES) return null;
+    try { body = JSON.parse(input); } catch { return null; }
+  }
+  if (!isPlainObject(body) || Object.keys(body).sort().join() !== RECORD_KEYS.join()) return null;
+  const { action, analytics, anonymousId, decidedAt, path, policyVersion, source } = body;
+  if (!versions.includes(policyVersion)) return null;
+  if (typeof analytics !== "boolean" || !CONSENT_ACTIONS.includes(action)) return null;
+  if ((action === "grant" && !analytics) || ((action === "deny" || action === "withdraw") && analytics)) return null;
+  if (typeof anonymousId !== "string" || !CONSENT_ANONYMOUS_ID_PATTERN.test(anonymousId)) return null;
+  if (source !== "web") return null;
+  if (typeof path !== "string" || normalizeConsentPath(path) !== path) return null;
+  const now = nowSeconds(options.now);
+  const maxAge = options.maxAgeSeconds ?? 31 * 24 * 60 * 60;
+  if (!Number.isSafeInteger(decidedAt) || decidedAt <= 0 || decidedAt > now + CLOCK_SKEW_SECONDS || now - decidedAt > maxAge) return null;
+  return Object.freeze({ action, analytics, anonymousId, decidedAt, path, policyVersion, source });
+}
+
+/**
+ * True when a request comes from `expectedOrigin`: its `Origin` header
+ * matches, or, with no `Origin`, the browser says `Sec-Fetch-Site:
+ * same-origin`. Takes a Request, a Headers, or a plain header object.
+ */
+export function isSameOriginRequest(request, expectedOrigin) {
+  const expected = new URL(expectedOrigin).origin;
+  const headers = request?.headers ?? request;
+  const get = (name) => {
+    if (typeof headers?.get === "function") return headers.get(name);
+    const key = Object.keys(headers ?? {}).find((candidate) => candidate.toLowerCase() === name);
+    const value = key === undefined ? undefined : headers[key];
+    return Array.isArray(value) ? value[0] : value;
+  };
+  const origin = get("origin");
+  if (origin) return origin === expected;
+  return get("sec-fetch-site") === "same-origin";
+}
+
+/**
+ * An `onChange` for createConsentManager that POSTs the record as JSON to a
+ * same-origin path. A failure throws an error whose `retryable` says whether
+ * the manager should keep the record and send it again on the next page
+ * (network errors, 429 and 5xx: yes; other 4xx: no — the server refused it).
+ */
+export function postConsentRecord(endpoint, options = {}) {
+  if (typeof endpoint !== "string" || !endpoint.startsWith("/") || endpoint.startsWith("//")) {
+    fail(`consent records go to a same-origin path such as "/api/consent"; got ${JSON.stringify(endpoint)}`);
+  }
+  return async (record) => {
+    const send = options.fetch ?? ((...args) => globalThis.fetch(...args));
+    let response;
+    try {
+      response = await send(endpoint, {
+        method: "POST",
+        credentials: "same-origin",
+        keepalive: true,
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(record),
+      });
+    } catch (cause) {
+      throw Object.assign(new Error("consent record was not sent"), { retryable: true, cause });
+    }
+    if (!response.ok) {
+      throw Object.assign(new Error(`consent record was refused (${response.status})`), { retryable: response.status === 429 || response.status >= 500 });
+    }
+  };
+}
+
+function randomId(scope) {
+  const crypto = scope?.crypto ?? globalThis.crypto;
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+const isConsentCommand = (item) => item !== null && typeof item === "object" && item[0] === "consent";
+
+/**
+ * The browser side. Create it once per page (module scope is fine — it does
+ * nothing until `start()`), mount the banner, which calls `start()`, or call
+ * `start()` yourself in a framework-free page.
+ */
+export function createConsentManager(options) {
+  const policyVersion = checkVersion(options?.policyVersion);
+  const gtm = options.gtm === undefined ? undefined : checkGtm(options.gtm);
+  const cookieName = checkCookieName(options.cookieName ?? CONSENT_COOKIE_NAME);
+  const cookieDomain = options.cookieDomain === undefined ? undefined : checkDomain(options.cookieDomain);
+  const maxAgeSeconds = checkMaxAge(options.maxAgeSeconds ?? CONSENT_MAX_AGE_SECONDS);
+  const measurementIds = (options.measurementIds ?? []).map(checkMeasurementId);
+  // ga-disable-<id> is the only switch that stops a GA4 tag Tag Manager has
+  // already initialised: its own listeners (history page_view, scroll,
+  // outbound clicks) bypass the dataLayer gate and would keep sending
+  // cookieless pings to Google until the page reloads.
+  if (gtm !== undefined && measurementIds.length === 0) {
+    fail("a consent manager that loads Tag Manager needs measurementIds (the GA4 streams the container sends to), so a withdrawal can switch them off");
+  }
+  const pendingKey = `${cookieName}_pending`;
+  const listeners = new Set();
+  const inFlight = new Set();
+  let started = false;
+  let dismissed = false;
+  let analyticsOn = false;
+  // The decision made on this page, for when the browser refuses the cookie:
+  // the choice still holds until the page is left, so the bar does not stay
+  // up after a click as if nothing happened.
+  let decidedHere = null;
+
+  const scope = () => options.window ?? (typeof window === "undefined" ? undefined : window);
+  const now = () => (options.now ? options.now() : Date.now());
+  const readRaw = () => {
+    const w = scope();
+    return w ? parseConsentCookie(cookieValue(w.document.cookie, cookieName)) : null;
+  };
+  const current = (candidate) => (candidate && candidate.v === policyVersion && isFresh(candidate, { now: now(), maxAgeSeconds }) ? candidate : null);
+  const state = () => current(readRaw()) ?? current(decidedHere);
+  const emit = (event) => {
+    for (const listener of [...listeners]) {
+      try { listener(event); } catch (error) { queueMicrotask(() => { throw error; }); }
+    }
+  };
+  const consentCommand = (...args) => {
+    const w = scope();
+    w.dataLayer = w.dataLayer || [];
+    // Tag Manager reads gtag commands only as `arguments` objects.
+    (function g() { w.dataLayer.push(arguments); })(...args);
+  };
+
+  // While analytics is not granted, the page's dataLayer accepts consent
+  // commands and drops everything else, so events a product pushes before
+  // consent are not queued for a Tag Manager that loads later, and events
+  // after a withdrawal never reach the one that already loaded.
+  const installGate = () => {
+    const w = scope();
+    const layer = (w.dataLayer = w.dataLayer || []);
+    if (layer.push[GATE]) return;
+    const inner = layer.push;
+    const gated = function (...items) {
+      const pass = analyticsOn ? items : items.filter(isConsentCommand);
+      return pass.length > 0 ? inner.apply(this, pass) : this.length;
+    };
+    gated[GATE] = true;
+    layer.push = gated;
+  };
+
+  const readNonce = (document) => {
+    for (const selector of ['meta[property="csp-nonce"]', 'meta[name="csp-nonce"]']) {
+      const meta = document.querySelector(selector);
+      const value = meta && (meta.nonce || meta.getAttribute("nonce") || meta.getAttribute("content"));
+      if (value) return value;
+    }
+    const element = document.querySelector("[nonce]");
+    return (element && (element.nonce || element.getAttribute("nonce"))) || undefined;
+  };
+
+  const loadGtm = () => {
+    const w = scope();
+    if (gtm === undefined || !w) return;
+    const document = w.document;
+    if (document.querySelector(`script[src^="${GTM_SCRIPT_PREFIX}"]`)) return;
+    w.dataLayer.push({ "gtm.start": now(), event: "gtm.js" });
+    const script = document.createElement("script");
+    script.async = true;
+    script.src = `${GTM_SCRIPT_PREFIX}?id=${gtm}`;
+    const nonce = options.nonce ?? readNonce(document);
+    if (nonce) script.setAttribute("nonce", nonce);
+    const first = document.getElementsByTagName("script")[0];
+    if (first?.parentNode) first.parentNode.insertBefore(script, first);
+    else (document.head ?? document.documentElement).appendChild(script);
+  };
+
+  const deleteAnalyticsCookies = () => {
+    const w = scope();
+    const document = w.document;
+    const host = w.location?.hostname ?? "";
+    const labels = /^[0-9.]+$|^\[|:/.test(host) ? [] : host.split(".");
+    const domains = [undefined];
+    for (let index = 0; index <= labels.length - 2; index += 1) domains.push(labels.slice(index).join("."));
+    const names = new Set(
+      document.cookie.split(";").map((part) => part.split("=", 1)[0].trim()).filter((name) => GA_COOKIE_PATTERN.test(name)),
+    );
+    for (const name of names) {
+      for (const domain of domains) document.cookie = `${name}=; Max-Age=0; Path=/${domain ? `; Domain=${domain}` : ""}`;
+    }
+  };
+
+  const setGaDisabled = (disabled) => {
+    const w = scope();
+    for (const id of measurementIds) w[`ga-disable-${id}`] = disabled;
+  };
+
+  const apply = (granted) => {
+    const w = scope();
+    if (granted) {
+      analyticsOn = true;
+      setGaDisabled(false);
+      if (w.__siteConsent !== "granted") consentCommand("consent", "update", { analytics_storage: "granted" });
+      w.__siteConsent = "granted";
+      loadGtm();
+      return;
+    }
+    analyticsOn = false;
+    installGate();
+    if (w.__siteConsent === "granted") consentCommand("consent", "update", { analytics_storage: "denied" });
+    w.__siteConsent = "denied";
+    setGaDisabled(true);
+    deleteAnalyticsCookies();
+  };
+
+  const readPending = () => {
+    try {
+      const value = JSON.parse(scope()?.localStorage?.getItem(pendingKey) ?? "[]");
+      return Array.isArray(value) ? value : [];
+    } catch { return []; }
+  };
+  const writePending = (records) => {
+    try {
+      const storage = scope()?.localStorage;
+      if (!storage) return;
+      if (records.length === 0) storage.removeItem(pendingKey);
+      else storage.setItem(pendingKey, JSON.stringify(records.slice(-20)));
+    } catch { /* storage blocked: the record is lost, the cookie still holds the choice */ }
+  };
+  const deliver = (record) => {
+    if (!options.onChange) return;
+    const attempt = (async () => {
+      try { await options.onChange(record); } catch (error) {
+        if (error?.retryable !== false) writePending([...readPending(), record]);
+      }
+    })();
+    inFlight.add(attempt);
+    attempt.finally(() => inFlight.delete(attempt));
+  };
+
+  const start = () => {
+    const w = scope();
+    if (!w || started) return;
+    started = true;
+    analyticsOn = state()?.a === 1;
+    installGate();
+    if (w.__siteConsent === undefined) {
+      consentCommand("consent", "default", { ...CONSENT_MODE_DEFAULTS });
+      w.__siteConsent = "denied";
+    }
+    // The head may disagree with the cookie (another tab changed it after
+    // this page was rendered); the cookie wins.
+    if (analyticsOn) apply(true);
+    else if (w.__siteConsent === "granted") apply(false);
+    const pending = readPending();
+    if (pending.length > 0) {
+      writePending([]);
+      for (const record of pending) deliver(record);
+    }
+  };
+
+  const decide = (analytics) => {
+    const w = scope();
+    if (!w) throw new Error("consent decisions are made in a browser");
+    start();
+    const previous = state();
+    const action = !previous
+      ? (analytics ? "grant" : "deny")
+      : previous.a === 1 ? (analytics ? "update" : "withdraw") : (analytics ? "grant" : "update");
+    const next = Object.freeze({ v: policyVersion, a: analytics ? 1 : 0, t: nowSeconds(now()), id: previous?.id ?? readRaw()?.id ?? randomId(w) });
+    w.document.cookie = serializeConsentCookie(next, { name: cookieName, maxAgeSeconds, ...(cookieDomain ? { domain: cookieDomain } : {}) });
+    decidedHere = next;
+    dismissed = false;
+    apply(analytics);
+    const path = normalizeConsentPath(options.recordPath ? options.recordPath(w.location?.pathname ?? "/") : w.location?.pathname);
+    const record = Object.freeze({ policyVersion, analytics, action, anonymousId: next.id, decidedAt: next.t, source: "web", path });
+    emit({ type: "change", state: next, record });
+    deliver(record);
+    return record;
+  };
+
+  return Object.freeze({
+    policyVersion,
+    /** Applies the stored decision to this page: Consent Mode defaults, then Tag Manager only if granted. Idempotent; a no-op outside a browser. */
+    start,
+    state,
+    analyticsGranted: () => state()?.a === 1,
+    needsDecision: () => state() === null,
+    acceptAll: () => decide(true),
+    rejectAll: () => decide(false),
+    save: (choice) => decide(choice?.analytics === true),
+    withdraw: () => decide(false),
+    openSettings: () => emit({ type: "open-settings" }),
+    dismiss: () => { dismissed = true; emit({ type: "dismiss" }); },
+    dismissed: () => dismissed,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    /** Opens settings from any click on `[data-consent-settings]` under `root` (a footer link in a page without the Solid kit). */
+    bindTriggers(root) {
+      const target = root ?? scope()?.document;
+      if (!target) return () => {};
+      const onClick = (event) => {
+        if (!event.target?.closest?.("[data-consent-settings]")) return;
+        event.preventDefault();
+        emit({ type: "open-settings" });
+      };
+      target.addEventListener("click", onClick);
+      return () => target.removeEventListener("click", onClick);
+    },
+    /** Resolves when every record sent so far has been delivered or queued. */
+    settled: () => Promise.all([...inFlight]).then(() => undefined),
+  });
+}
+
+/** Default strings, Korean. Products pass these (or their own) to the banner. */
+export const CONSENT_MESSAGES_KO = Object.freeze({
+  regionLabel: "쿠키 동의",
+  title: "방문 통계에 쿠키를 써도 될까요?",
+  body: "동의하시면 Google Analytics로 어떤 페이지를 얼마나 보는지 통계를 냅니다. 데이터는 Google LLC(미국)로 전송되어 14개월 동안 보관되고, 광고에는 쓰지 않습니다. 동의하지 않아도 사이트의 모든 기능을 그대로 쓸 수 있고, 바닥글의 ‘쿠키 설정’에서 언제든 바꿀 수 있습니다.",
+  privacyLink: "개인정보처리방침",
+  acceptAll: "모두 허용",
+  rejectAll: "거부",
+  settings: "설정",
+  dismiss: "선택하지 않고 닫기",
+  settingsTitle: "쿠키 설정",
+  settingsIntro: "필수 쿠키는 사이트가 동작하는 데 필요해 항상 사용합니다. 방문 통계는 동의하실 때만 사용하며, 여기서 언제든 바꾸거나 철회할 수 있습니다.",
+  necessaryTitle: "필수",
+  necessaryBody: "서비스 제공과 보안, 법령상 의무를 위해 꼭 필요해 거부할 수 없는 쿠키입니다. 이 선택을 기억하는 쿠키도 여기에 속합니다.",
+  necessaryStatus: "항상 사용",
+  analyticsTitle: "방문 통계 (선택)",
+  analyticsBody: "Google Analytics 4로 방문한 페이지, 머문 시간, 기기·브라우저 종류를 가명 식별자와 함께 수집해 통계를 냅니다. 받는 곳: Google LLC(미국으로 국외 이전). 보관 기간: 14개월. 광고에는 쓰지 않습니다.",
+  analyticsSwitch: "방문 통계 허용",
+  save: "선택 저장",
+  close: "닫기",
+  saved: "쿠키 설정을 저장했습니다.",
+  trigger: "쿠키 설정",
+});
+
+/** Default strings, English. */
+export const CONSENT_MESSAGES_EN = Object.freeze({
+  regionLabel: "Cookie consent",
+  title: "May we use cookies for visit statistics?",
+  body: "If you agree, Google Analytics counts which pages are viewed and for how long. The data goes to Google LLC in the United States, is kept for 14 months, and is never used for ads. Everything on this site works without it, and you can change your choice at any time under “Cookie settings” in the footer.",
+  privacyLink: "Privacy policy",
+  acceptAll: "Accept all",
+  rejectAll: "Reject",
+  settings: "Settings",
+  dismiss: "Close without choosing",
+  settingsTitle: "Cookie settings",
+  settingsIntro: "Necessary cookies keep the site working and are always on. Visit statistics run only with your consent, and you can change or withdraw it here at any time.",
+  necessaryTitle: "Necessary",
+  necessaryBody: "Needed to provide the service, keep it secure and meet legal obligations, so they cannot be turned off. The cookie that remembers this choice is one of them.",
+  necessaryStatus: "Always on",
+  analyticsTitle: "Visit statistics (optional)",
+  analyticsBody: "Google Analytics 4 records the pages you view, time spent, and device and browser type under a pseudonymous ID to produce statistics. Recipient: Google LLC (transferred to the United States). Kept for 14 months. Never used for ads.",
+  analyticsSwitch: "Allow visit statistics",
+  save: "Save choices",
+  close: "Close",
+  saved: "Your cookie settings are saved.",
+  trigger: "Cookie settings",
+});

package/src/core/index.d.mts

@@ -5,3 +5,4 @@ export * from "./geo.mjs";
 export * from "./publisher.mjs";
 export * from "./gtm.mjs";
 export * from "./fonts.mjs";
+export * from "./consent.mjs";

package/src/core/index.mjs

@@ -5,3 +5,7 @@ export { VerifiedFactRegistry, buildVerifiedJsonLd, renderLlmsTxt } from "./geo.
 export { definePublisher, buildPublisher, serializeJsonLd, renderPublisherHtml } from "./publisher.mjs";
 export { GTM_CONTAINER_ID_PATTERN, GTM_CSP_SOURCES, gtmHeadScript, gtmNoscriptIframe } from "./gtm.mjs";
 export { FAMILY_FONT_PRELOAD_FILE, fontPreloadLinks } from "./fonts.mjs";
+export {
+  CONSENT_COOKIE_NAME, CONSENT_MESSAGES_EN, CONSENT_MESSAGES_KO, CONSENT_MODE_DEFAULTS, CONSENT_RESPONSE_HEADERS, analyticsConsented, consentCookieGrantsAnalytics,
+  consentHeadScript, createConsentManager, isSameOriginRequest, parseConsentRecord, postConsentRecord, readConsentCookie,
+} from "./consent.mjs";

package/src/tanstack-start.d.mts

@@ -9,9 +9,20 @@ import type { SiteLocale } from "./core/locales.mjs";
 /**
  * `icons: true` appends brandIconLinks() (the /brand default); an object passes its options through. Omitted, no icon links are emitted.
  * `fontPreload` appends fontPreloadLinks(fontPreload) — the same-origin URL(s) the product's bundler gave the family face, e.g. Geist Latin imported with `?url` (D-033). Omitted, no preload links are emitted.
- * `gtm` adds Google Tag Manager's head loader for that container id as `scripts[0]`; omitted or `undefined` (a route without Tag Manager), the result has no `scripts` key.
+ * `gtm` adds Google Tag Manager's head loader for that container id as `scripts[0]` — unconditionally, without consent. Kept for compatibility; family products use `consent` instead (D-034).
+ * `consent` adds consentHeadEntry(consent) as `scripts[0]`: Consent Mode defaults, plus the loader only when the cookie grants analytics for the current policy version. Passing both `gtm` and `consent` throws TypeError.
+ * Neither (a route without Tag Manager): the result has no `scripts` key.
  */
-export interface TanStackHeadOptions { icons?: boolean | { basePath?: string }; fontPreload?: string | readonly string[] | undefined; gtm?: string | undefined }
+export interface TanStackHeadOptions { icons?: boolean | { basePath?: string }; fontPreload?: string | readonly string[] | undefined; gtm?: string | undefined; consent?: ConsentHeadOptions | undefined }
+/**
+ * `cookie`: the request's Cookie header on the server, `document.cookie` in the browser (createIsomorphicFn), so hydration sees the same script.
+ * `gtm`: the container to load once analytics is granted; omitted, the entry is the Consent Mode defaults only.
+ */
+export interface ConsentHeadOptions { policyVersion: string; cookie: string | null | undefined; gtm?: string | undefined; cookieName?: string | undefined }
+/** The consent-gated `scripts` entry (inline script body only; the router adds `ssr.nonce`). Throws RangeError for a malformed id or policy version. */
+export declare function consentHeadEntry(options: ConsentHeadOptions): GtmHeadEntry;
+/** Send on every route that uses `consent` (the route's `headers` option): the head differs per visitor, so the page must never sit in a shared cache. */
+export { CONSENT_RESPONSE_HEADERS } from "./core/consent.mjs";
 /** A route `head().scripts` entry: the loader body only. The router adds `ssr.nonce` when it renders the tag. Throws RangeError for a malformed id. */
 export interface GtmHeadEntry { children: string }
 export declare function gtmHeadEntry(containerId: string): GtmHeadEntry;

package/src/tanstack-start.mjs

@@ -1,6 +1,14 @@
 import { brandIconLinks } from "./core/seo.mjs";
 import { gtmHeadScript } from "./core/gtm.mjs";
 import { fontPreloadLinks } from "./core/fonts.mjs";
+import { consentCookieGrantsAnalytics, consentHeadScript } from "./core/consent.mjs";
+
+/**
+ * Send these on every route that uses `consent` (TanStack Start: the route's
+ * `headers` option). The head differs per visitor's cookie, so the page must
+ * never sit in a shared cache.
+ */
+export { CONSENT_RESPONSE_HEADERS } from "./core/consent.mjs";
 
 /**
  * A route `head().scripts` entry that loads Google Tag Manager (D-031).
@@ -17,11 +25,33 @@ export function gtmHeadEntry(containerId) {
   return { children: gtmHeadScript(containerId) };
 }
 
+/**
+ * The consent-gated head entry (D-034): one inline script. Without a current
+ * analytics grant in `cookie` it only pushes Consent Mode defaults (all
+ * denied) into the page's dataLayer — nothing contacts Google. With one, it
+ * also grants `analytics_storage` and runs Google's Tag Manager loader.
+ *
+ * `cookie` is the Cookie header on the server and `document.cookie` in the
+ * browser (TanStack Start: createIsomorphicFn), so both sides of hydration
+ * render the same script. Only the consent cookie is read from it; nothing
+ * from it is written into the page. Like gtmHeadEntry, no nonce: the router
+ * stamps `ssr.nonce`.
+ */
+export function consentHeadEntry(options) {
+  const granted = consentCookieGrantsAnalytics(options?.cookie, {
+    policyVersion: options?.policyVersion,
+    ...(options.cookieName === undefined ? {} : { cookieName: options.cookieName }),
+  });
+  return { children: consentHeadScript({ granted, gtm: options.gtm }) };
+}
+
 // `icons` is opt-in: the adapter cannot know where (or whether) a product
 // serves the linq-brand files, and a head that links icons the server 404s
 // is worse than one that links none. `true` takes the /brand default.
 // `gtm` is opt-in the same way, and per route: the product decides which
 // pages carry Tag Manager (public marketing and legal pages, not consoles).
+// It loads Tag Manager unconditionally and stays for compatibility; products
+// switch to `consent` (D-034), which loads it only after an opt-in.
 // `fontPreload` is opt-in too: only the product knows the hashed URL its
 // bundler gave the face (D-033). Appended after the icons.
 export function toTanStackHead(metadata, options = {}) {
@@ -49,7 +79,11 @@ export function toTanStackHead(metadata, options = {}) {
       ...(options.fontPreload === undefined ? [] : fontPreloadLinks(options.fontPreload)),
     ],
   };
-  if (options.gtm !== undefined) head.scripts = [gtmHeadEntry(options.gtm)];
+  if (options.gtm !== undefined && options.consent !== undefined) {
+    throw new TypeError("toTanStackHead: pass the container id as consent.gtm, not both gtm and consent — gtm alone loads Tag Manager without consent");
+  }
+  if (options.consent !== undefined) head.scripts = [consentHeadEntry(options.consent)];
+  else if (options.gtm !== undefined) head.scripts = [gtmHeadEntry(options.gtm)];
   return head;
 }