@owlmeans/consent 0.1.18-rc.10

package/src/i18n/uk.json

@@ -0,0 +1,36 @@
+{
+  "title": "Налаштування файлів cookie",
+  "description": "Ми використовуємо файли cookie, щоб покращити ваш досвід перегляду, показувати персоналізовану рекламу чи вміст і аналізувати наш трафік. Натискаючи «Прийняти всі», ви погоджуєтеся на використання файлів cookie.",
+  "essential": "Необхідні файли cookie",
+  "essentialDesc": "Потрібні для роботи сайту — вхід, безпека та збереження вашого вибору щодо файлів cookie і мови інтерфейсу. Їх не можна вимкнути.",
+  "analytics": "Аналітичні файли cookie",
+  "analyticsDesc": "Допомагають нам покращувати наш вебсайт, збираючи та надаючи інформацію про його використання.",
+  "marketing": "Маркетингові файли cookie",
+  "marketingDesc": "Використовуються для відстеження відвідувачів на різних вебсайтах для показу релевантної та цікавої реклами.",
+  "required": "Обов'язково",
+  "acceptAll": "Прийняти всі",
+  "acceptAndContinue": "Прийняти й продовжити",
+  "savePreferences": "Зберегти налаштування",
+  "policyLink": "Політика щодо файлів cookie",
+  "openPreferences": "Налаштування файлів cookie",
+  "close": "Закрити",
+  "loginReason": "Вхід зберігає сеансовий файл cookie. Прийміть необхідні файли cookie, щоб продовжити.",
+  "manage": "Змінити налаштування",
+  "policyTitle": "Політика щодо файлів cookie",
+  "policyIntro": "Ця сторінка описує файли cookie та подібні сховища, які використовує цей застосунок, і як ними керувати.",
+  "policyStorage": "Ваш вибір зберігається в цьому браузері під ключем «{{key}}» — і в локальному сховищі, і у файлі cookie.",
+  "policyRetention": "Запис зберігається {{days}} днів, після чого ми запитаємо знову.",
+  "policyOperator": "Цей застосунок належить {{operator}}.",
+  "policyContact": "Ознайомтеся з їхньою політикою конфіденційності та умовами користування, щоб дізнатися, як вони обробляють ваші дані.",
+  "policyServicesOf": "Сервіси — {{category}}",
+  "policyOtherServices": "Інші сервіси",
+  "policyOtherServicesDesc": "Сервіси, які цей застосунок використовує поза переліченими вище категоріями.",
+  "policyProvider": "Постачальник",
+  "policyPurpose": "Мета",
+  "policyCookies": "Файли cookie",
+  "policyServicePrivacy": "Політика конфіденційності: {{provider}}",
+  "privacy": "Політика конфіденційності",
+  "terms": "Умови користування",
+  "domains": "Цей вибір застосовується до {{domains}}.",
+  "policyDomains": "Цей вибір застосовується до таких доменів:"
+}

package/src/i18n.ts

@@ -0,0 +1,39 @@
+import { CONSENT_LOCALES } from './consts.js'
+import type { ConsentLocale } from './types.js'
+
+import en from './i18n/en.json' with { type: 'json' }
+import pl from './i18n/pl.json' with { type: 'json' }
+import ru from './i18n/ru.json' with { type: 'json' }
+import be from './i18n/be.json' with { type: 'json' }
+import uk from './i18n/uk.json' with { type: 'json' }
+import es from './i18n/es.json' with { type: 'json' }
+import de from './i18n/de.json' with { type: 'json' }
+import fr from './i18n/fr.json' with { type: 'json' }
+
+/**
+ * The dialog's copy, in the box.
+ *
+ * Carried here rather than registered into an i18n framework because one of the three consumers is
+ * an Astro site with React islands and no OwlMeans i18n at all — and a consent dialog that renders
+ * raw keys is worse than no dialog. An application that HAS translations passes `translate` and
+ * overrides every one of these.
+ */
+export const DEFAULT_CONSENT_MESSAGES: Record<ConsentLocale, Record<string, string>> = {
+  en, pl, ru, be, uk, es, de, fr,
+}
+
+export const normalizeLocale = (locale?: string): ConsentLocale => {
+  const base = (locale ?? 'en').toLowerCase().split('-')[0]
+
+  return CONSENT_LOCALES.includes(base as ConsentLocale) ? base as ConsentLocale : 'en'
+}
+
+/** `(key, defaultValue) => string`, the house shape, backed by the built-in bundle. */
+export const defaultConsentTranslate = (locale?: string) =>
+  (key: string, defaultValue: string): string =>
+    DEFAULT_CONSENT_MESSAGES[normalizeLocale(locale)]?.[key] ?? defaultValue
+
+/** Substitute `{{name}}` placeholders. Enough for the two the policy page needs. */
+export const interpolate = (text: string, values: Record<string, string | number>): string =>
+  text.replace(/\{\{([a-z]+)\}\}/gi, (whole, name: string) =>
+    values[name] != null ? String(values[name]) : whole)

package/src/index.ts

@@ -0,0 +1,14 @@
+export type * from './types.js'
+export * from './consts.js'
+export * from './storage.js'
+export * from './gtm.js'
+export * from './store.js'
+export * from './i18n.js'
+export type { ConsentPlugin } from './types.js'
+export {
+  registerConsentPlugin, consentPlugins, decorateConsentUrl, consentDomains, adoptConsent,
+  startConsentPlugins, adoptConsentLanguage,
+} from './plugins.js'
+export type { ConsentLinkPayload } from './types.js'
+export { consentLinker, encodeConsentLink, decodeConsentLink, stripConsentLinkParam, consentLinkerScript, writeConsentLanguage } from './linker.js'
+export { CONSENT_LINK_PARAM, CONSENT_LINK_MAX_AGE, CONSENT_LINK_SKEW } from './consts.js'

package/src/linker.ts

@@ -0,0 +1,369 @@
+import { CONSENT_COOKIE_DAYS, CONSENT_KEY, CONSENT_LANGUAGE_KEY, CONSENT_SCHEMA_VERSION, DEFAULT_CONSENT_CATEGORIES, CONSENT_LINK_MAX_AGE, CONSENT_LINK_PARAM, CONSENT_LINK_SKEW } from './consts.js'
+import type { ConsentPlugin, ConsentCategory, ConsentOptions, ConsentRecord, ConsentLinkPayload } from './types.js'
+import { decorateConsentUrl } from './plugins.js'
+import { readConsent } from './storage.js'
+import { CONSENT_LINK_VERSION, LANGUAGE_TAG } from './consts.local.js'
+
+
+const categoriesOf = (opts?: ConsentOptions): ConsentCategory[] =>
+  opts?.categories ?? DEFAULT_CONSENT_CATEGORIES
+
+const optionalOf = (opts?: ConsentOptions): ConsentCategory[] =>
+  categoriesOf(opts).filter(category => category.required !== true)
+
+const toBase64Url = (json: string): string =>
+  btoa(json).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+
+const fromBase64Url = (value: string): string | null => {
+  try {
+    let padded = value.replace(/-/g, '+').replace(/_/g, '/')
+    while (padded.length % 4 !== 0) {
+      padded += '='
+    }
+
+    return atob(padded)
+  } catch {
+    return null
+  }
+}
+
+/** The language this document is written in — `<html lang>`, the one signal every page has. */
+const documentLanguage = (): string | null => {
+  if (typeof document === 'undefined') {
+    return null
+  }
+  const lang = document.documentElement?.lang?.trim() ?? ''
+
+  return LANGUAGE_TAG.test(lang) ? lang.toLowerCase() : null
+}
+
+/**
+ * The link parameter's value: the current document's decision as `c` (one `0`/`1` per optional
+ * category — empty while `record` is `null`, i.e. before the visitor has decided) and, when
+ * `opts.linker.language` is set, the page's language as `l`.
+ */
+export const encodeConsentLink = (record: ConsentRecord | null, opts?: ConsentOptions): string => {
+  const c: Record<string, 0 | 1> = {}
+  if (record != null) {
+    for (const category of optionalOf(opts)) {
+      c[category.key] = record[category.key] === true ? 1 : 0
+    }
+  }
+  const language = opts?.linker?.language != null ? documentLanguage() : null
+  const payload: ConsentLinkPayload = {
+    v: CONSENT_LINK_VERSION, c, t: Math.floor(Date.now() / 1000), ...(language != null ? { l: language } : {}),
+  }
+
+  return toBase64Url(JSON.stringify(payload))
+}
+
+/** Parse-only — no trust decision here, that is `consentLinker(opts).adopt`'s job. Never throws. */
+export const decodeConsentLink = (value: string): ConsentLinkPayload | null => {
+  const json = fromBase64Url(value)
+  if (json == null) {
+    return null
+  }
+  try {
+    const parsed = JSON.parse(json) as unknown
+    if (parsed == null || typeof parsed !== 'object') {
+      return null
+    }
+    const { v, c, t, l } = parsed as Record<string, unknown>
+    if (v !== CONSENT_LINK_VERSION || typeof t !== 'number' || c == null || typeof c !== 'object') {
+      return null
+    }
+
+    return {
+      v: CONSENT_LINK_VERSION, c: c as Record<string, 0 | 1>, t,
+      // A malformed language is dropped, never a reason to refuse the decision beside it.
+      ...(typeof l === 'string' && LANGUAGE_TAG.test(l) ? { l: l.toLowerCase() } : {}),
+    }
+  } catch {
+    return null
+  }
+}
+
+const referrerHostname = (): string | null => {
+  if (typeof document === 'undefined' || document.referrer === '') {
+    return null
+  }
+  try {
+    return new URL(document.referrer).hostname
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The payload of the link this document was opened from, once it has passed every check that does
+ * not depend on WHAT it carries: the parameter decodes and its version matches, its timestamp is
+ * fresh (and not from the future beyond the allowed skew), and the request's referrer host is a
+ * LISTED domain — read from `document.referrer`, never from the parameter itself. `null` otherwise.
+ */
+const trustedPayload = (opts: ConsentOptions): ConsentLinkPayload | null => {
+  const linker = opts.linker
+  if (linker == null || typeof location === 'undefined') {
+    return null
+  }
+  const raw = new URLSearchParams(location.search).get(linker.param ?? CONSENT_LINK_PARAM)
+  if (raw == null) {
+    return null
+  }
+  const decoded = decodeConsentLink(raw)
+  if (decoded == null) {
+    return null
+  }
+  const now = Math.floor(Date.now() / 1000)
+  const maxAge = linker.maxAge ?? CONSENT_LINK_MAX_AGE
+  if (now - decoded.t > maxAge || decoded.t - now > CONSENT_LINK_SKEW) {
+    return null
+  }
+  const referrer = referrerHostname()
+  if (referrer == null || !linker.domains.includes(referrer)) {
+    return null
+  }
+
+  return decoded
+}
+
+/** The entry of `supported` that `language` names — exactly, else by its base tag — or `null`. */
+const supportedLanguage = (language: string, supported: string[]): string | null => {
+  const wanted = language.toLowerCase()
+  const exact = supported.find(candidate => candidate.toLowerCase() === wanted)
+  if (exact != null) {
+    return exact
+  }
+  const base = wanted.split(/[-_]/)[0]
+
+  return supported.find(candidate => candidate.toLowerCase() === base) ?? null
+}
+
+/**
+ * Persist an adopted language where the application's i18n layer reads its explicit choice from —
+ * `linker.language.storageKey`, `owlmeans-lng` by default. Unconditional: the interface language is
+ * strictly necessary storage (the visitor picked it, and the site cannot speak to them without it),
+ * so no cookie decision — none yet, a refusal, an old record — stands between it and the device.
+ *
+ * It overwrites what is there on purpose: the carried language is the one the visitor was reading a
+ * moment ago, which outranks a choice they made on this domain some other day. Storage that refuses
+ * the write is not an error. Returns whether the language was written.
+ */
+export const writeConsentLanguage = (language: string, opts?: ConsentOptions): boolean => {
+  try {
+    localStorage.setItem(opts?.linker?.language?.storageKey ?? CONSENT_LANGUAGE_KEY, language)
+
+    return true
+  } catch {
+    // Private modes and blocked storage both throw; the app simply keeps choosing its own language.
+    return false
+  }
+}
+
+/** Escape `<` inside a JSON literal meant for an inline `<script>` — the same discipline every
+ * caller of `consentBootstrapScript`/`consentGateScript` already owes the HTML it lands in, applied
+ * here at the source since this fragment's dynamic values (a configured domain, a storage key) are
+ * least likely to have been reviewed for it by whoever composes the final page. */
+const jsonForScript = (value: unknown): string => JSON.stringify(value).replace(/</g, '\\u003c')
+
+/**
+ * Cross-domain consent: share this decision, and adopt one, between the domains named in
+ * `opts.linker.domains`.
+ *
+ * `start` decorates outgoing first-party links; `adopt` reads and validates an incoming one;
+ * `domains` discloses the list a dialog or policy page names. `decorate` is generic (a bare `URL`,
+ * no DOM) so the same trust rule serves a real anchor click and a programmatic navigation
+ * (`decorateConsentUrl`) alike — the `rel="noreferrer"` exemption is a DOM-only concept and is
+ * therefore checked by `start`'s click handler, never here.
+ */
+export const consentLinker = (): ConsentPlugin => {
+  let installed = false
+
+  return {
+    alias: 'linker',
+
+    start: opts => {
+      if (typeof document === 'undefined' || installed || opts.linker == null) {
+        return
+      }
+      installed = true
+
+      const onNavigate = (event: Event): void => {
+        const target = event.target
+        const anchor = target instanceof Element ? target.closest('a[href]') : null
+        if (!(anchor instanceof HTMLAnchorElement)) {
+          return
+        }
+        // The trust rule keeps `noreferrer` links untouched: a link that refuses to disclose the
+        // referrer is refusing exactly the signal the receiving side's `adopt` needs to trust it.
+        if (/\bnoreferrer\b/.test(anchor.getAttribute('rel') ?? '')) {
+          return
+        }
+        // No decision yet is still worth a decoration when a language rides along with it.
+        const record = readConsent(opts)
+        if (record == null && opts.linker?.language == null) {
+          return
+        }
+        let url: URL
+        try {
+          url = new URL(anchor.href, location.href)
+        } catch {
+          return
+        }
+        const decorated = decorateConsentUrl(url, record, opts)
+        if (decorated.toString() !== url.toString()) {
+          anchor.href = decorated.toString()
+        }
+      }
+
+      // Capture phase: this must decide before the click's own navigation (or a framework router
+      // intercepting it) reads `href`. `auxclick`/`contextmenu` cover a middle-click and "copy link
+      // address" — an address copied undecorated is a link that silently fails to carry the choice.
+      document.addEventListener('click', onNavigate, true)
+      document.addEventListener('auxclick', onNavigate, true)
+      document.addEventListener('contextmenu', onNavigate, true)
+    },
+
+    decorate: (url, record, opts) => {
+      const linker = opts.linker
+      const host = typeof location !== 'undefined' ? location.hostname : ''
+      if (linker == null || url.hostname === host || !linker.domains.includes(url.hostname)) {
+        return null
+      }
+      // A link carries a decision, a language, or both; with neither there is nothing to say.
+      if (record == null && (linker.language == null || documentLanguage() == null)) {
+        return null
+      }
+      const next = new URL(url.toString())
+      next.searchParams.set(linker.param ?? CONSENT_LINK_PARAM, encodeConsentLink(record, opts))
+
+      return next
+    },
+
+    adopt: opts => {
+      const decoded = trustedPayload(opts)
+      if (decoded == null) {
+        return null
+      }
+      const optional = optionalOf(opts)
+      if (!optional.every(category => decoded.c[category.key] === 0 || decoded.c[category.key] === 1)) {
+        return null
+      }
+
+      const record: ConsentRecord = { v: CONSENT_SCHEMA_VERSION }
+      for (const category of categoriesOf(opts)) {
+        record[category.key] = category.required === true || decoded.c[category.key] === 1
+      }
+
+      return record
+    },
+
+    adoptLanguage: opts => {
+      const supported = opts.linker?.language?.supported
+      const decoded = supported != null ? trustedPayload(opts) : null
+
+      return decoded?.l != null && supported != null ? supportedLanguage(decoded.l, supported) : null
+    },
+
+    domains: opts => opts.linker?.domains ?? [],
+  }
+}
+
+/**
+ * Remove the link parameter from the visible URL, keeping every other parameter and the hash — the
+ * real-TS equivalent of what {@link consentLinkerScript}'s embedded fragment already did inline.
+ * Idempotent: a page with no head script calls this from `consentStore.init` and it strips once; a
+ * page that ALSO carried the head script finds the parameter already gone and does nothing.
+ */
+export const stripConsentLinkParam = (opts: ConsentOptions): void => {
+  const linker = opts.linker
+  if (linker == null || typeof location === 'undefined' || typeof history === 'undefined') {
+    return
+  }
+  const param = linker.param ?? CONSENT_LINK_PARAM
+  const url = new URL(location.href)
+  if (!url.searchParams.has(param)) {
+    return
+  }
+  url.searchParams.delete(param)
+  try {
+    history.replaceState(history.state, '', `${url.pathname}${url.search}${url.hash}`)
+  } catch {
+    // A sandboxed/embedded context may refuse history writes; the parameter just stays visible.
+  }
+}
+
+/**
+ * The inline `<head>` fragment that adopts a decorated link's decision and strips the parameter —
+ * standalone, so a page can stamp it even where nothing else here runs (a legal page with no tag
+ * script). `@owlmeans/web-gtm`'s `consentBootstrapScript` embeds this SAME fragment right after
+ * pushing Consent Mode's defaults, so a page that has both never runs it twice with different
+ * effect — the second attempt finds the parameter already gone and does nothing.
+ *
+ * Mirrors `consentLinker().adopt` exactly (v2, referrer + freshness/skew + full optional coverage +
+ * no existing record), but as hand-rolled JS text rather than a call into this module — the same
+ * discipline `consentBootstrapScript`/`consentGateScript` already follow, because this has to run
+ * before any bundle (this module included) has loaded. The parameter is ALWAYS stripped via
+ * `history.replaceState`, whether or not the trust rule accepts it: a stale or foreign `owlcc` is
+ * exactly as much noise as an adopted one, and neither belongs in the visible URL or in what a page
+ * reload, a shared link or a browser history entry carries forward.
+ */
+export const consentLinkerScript = (opts: ConsentOptions): string => {
+  const linker = opts.linker
+  if (linker == null) {
+    return ''
+  }
+  const param = jsonForScript(linker.param ?? CONSENT_LINK_PARAM)
+  const domains = jsonForScript(linker.domains)
+  const storageKey = jsonForScript(opts.storageKey ?? CONSENT_KEY)
+  const optionalKeys = jsonForScript(optionalOf(opts).map(category => category.key))
+  const allCategories = jsonForScript(
+    categoriesOf(opts).map(category => ({ key: category.key, required: category.required === true }))
+  )
+  const maxAge = linker.maxAge ?? CONSENT_LINK_MAX_AGE
+  const skew = CONSENT_LINK_SKEW
+  const cookieDays = opts.cookieDays ?? CONSENT_COOKIE_DAYS
+  const version = CONSENT_LINK_VERSION
+  // The language rides the same trust decision and is written unconditionally — it is strictly
+  // necessary storage, whatever the cookie decision is. Mirrors `supportedLanguage` +
+  // `writeConsentLanguage`; empty for a page that does not receive a language.
+  const language = linker.language?.supported != null
+    ? `var L=${jsonForScript(linker.language.supported)};` +
+      `if(typeof j.l==='string'){var lc=j.l.toLowerCase(),lm=null,q;` +
+      `for(q=0;q<L.length;q++){if(String(L[q]).toLowerCase()===lc){lm=L[q];break}}` +
+      `if(!lm){lc=lc.split(/[-_]/)[0];for(q=0;q<L.length;q++){if(String(L[q]).toLowerCase()===lc){lm=L[q];break}}}` +
+      `if(lm){try{w.localStorage.setItem(${jsonForScript(linker.language.storageKey ?? CONSENT_LANGUAGE_KEY)},lm)}catch(e){}}}`
+    : ''
+
+  return `(function(w,d){` +
+    `var p=${param};var qs;try{qs=new URLSearchParams(location.search)}catch(e){return}` +
+    `var raw=qs.get(p);if(raw==null)return;` +
+    `qs.delete(p);var rest=qs.toString();` +
+    `var url=location.pathname+(rest?('?'+rest):'')+location.hash;` +
+    `try{history.replaceState(history.state,'',url)}catch(e){}` +
+    `try{` +
+      `var b=raw.replace(/-/g,'+').replace(/_/g,'/');while(b.length%4)b+='=';` +
+      `var j=JSON.parse(atob(b));` +
+      `if(!j||j.v!==${version}||typeof j.t!=='number'||!j.c||typeof j.c!=='object')return;` +
+      `var now=Math.floor(Date.now()/1000);` +
+      `if(now-j.t>${maxAge}||j.t-now>${skew})return;` +
+      `var ref=null;try{ref=new URL(d.referrer).hostname}catch(e){}` +
+      `if(!ref||${domains}.indexOf(ref)<0)return;` +
+      `var existing=null;try{existing=w.localStorage.getItem(${storageKey})}catch(e){}` +
+      `if(!existing){var cp=('; '+d.cookie).split('; '+${storageKey}+'=');` +
+        `if(cp.length===2)existing=cp.pop().split(';').shift()}` +
+      `if(!existing){` +
+        `var keys=${optionalKeys},ok=true;` +
+        `for(var i=0;i<keys.length;i++){if(j.c[keys[i]]!==0&&j.c[keys[i]]!==1){ok=false;break}}` +
+        `if(ok){` +
+          `var cats=${allCategories},rec={v:${version}};` +
+          `for(var k=0;k<cats.length;k++){var c=cats[k];rec[c.key]=c.required||j.c[c.key]===1}` +
+          `var val=JSON.stringify(rec);` +
+          `try{w.localStorage.setItem(${storageKey},val)}catch(e){}` +
+          `var exp=new Date(Date.now()+${cookieDays}*86400000).toUTCString();` +
+          `d.cookie=${storageKey}+'='+val+';expires='+exp+';path=/;SameSite=Lax'` +
+        `}` +
+      `}` +
+      language +
+    `}catch(e){}` +
+  `})(window,document)`
+}

package/src/plugins.ts

@@ -0,0 +1,88 @@
+import type { ConsentOptions, ConsentRecord, ConsentPlugin } from './types.js'
+
+/**
+ * Module-global by design, like `@owlmeans/client-auth/login`'s method/step registries: consent is
+ * one thing per document, not per component tree, and a plugin is installed once at bundle scope
+ * (an Astro island, a script tag, a React app) regardless of how many components read the store.
+ */
+const plugins = new Map<string, ConsentPlugin>()
+
+/** Register a plugin. Replace-by-alias; sorted by priority (higher first) on every read. */
+export const registerConsentPlugin = (plugin: ConsentPlugin): void => {
+  plugins.set(plugin.alias, plugin)
+}
+
+/** Every registered plugin, priority-sorted (higher first, ties keep insertion order). */
+export const consentPlugins = (): ConsentPlugin[] =>
+  [...plugins.values()].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+
+/**
+ * Ask every registered plugin to decorate `url` with this document's decision, in priority order,
+ * stopping at the first one that actually changes it. A plugin whose own rules refuse (a foreign
+ * host, a `noreferrer` link, no local decision yet) returns `null` and is skipped, not an error.
+ */
+export const decorateConsentUrl = (
+  url: string | URL, record: ConsentRecord | null, opts: ConsentOptions
+): URL => {
+  let result = url instanceof URL ? url : new URL(url)
+  for (const plugin of consentPlugins()) {
+    if (plugin.decorate == null) {
+      continue
+    }
+    const decorated = plugin.decorate(result, record, opts)
+    if (decorated != null) {
+      result = decorated
+    }
+  }
+
+  return result
+}
+
+/**
+ * Every domain this document's decision is disclosed to, current host first, deduplicated — what a
+ * dialog or a policy page lists. A plugin that runs on this host but names no domains of its own
+ * (nothing registered, or `domains` not implemented) leaves the list at just the current host,
+ * which is always correct to show even with no plugin at all.
+ */
+export const consentDomains = (opts: ConsentOptions): string[] => {
+  const host = typeof location !== 'undefined' ? location.hostname : ''
+  const named = consentPlugins().flatMap(plugin => plugin.domains?.(opts) ?? [])
+
+  return [...new Set([host, ...named].filter(domain => domain !== ''))]
+}
+
+/** Try every registered plugin's `adopt`, in priority order, and use the first decision offered. */
+export const adoptConsent = (opts: ConsentOptions): ConsentRecord | null => {
+  for (const plugin of consentPlugins()) {
+    const adopted = plugin.adopt?.(opts)
+    if (adopted != null) {
+      return adopted
+    }
+  }
+
+  return null
+}
+
+/**
+ * Try every registered plugin's `adoptLanguage`, in priority order, and use the first language
+ * offered. The caller persists it (`writeConsentLanguage`) — and has to do that BEFORE its i18n
+ * layer reads storage, which is why the inline `<head>` fragment (`consentLinkerScript`) is the
+ * one that normally does.
+ */
+export const adoptConsentLanguage = (opts: ConsentOptions): string | null => {
+  for (const plugin of consentPlugins()) {
+    const adopted = plugin.adoptLanguage?.(opts)
+    if (adopted != null) {
+      return adopted
+    }
+  }
+
+  return null
+}
+
+/** Run every registered plugin's `start`, in priority order. `consentStore.init` calls this once. */
+export const startConsentPlugins = (opts: ConsentOptions): void => {
+  for (const plugin of consentPlugins()) {
+    plugin.start?.(opts)
+  }
+}

package/src/storage.ts

@@ -0,0 +1,96 @@
+import {
+  CONSENT_COOKIE_DAYS, CONSENT_ESSENTIAL, CONSENT_KEY, CONSENT_SCHEMA_VERSION,
+} from './consts.js'
+import type { ConsentOptions, ConsentRecord } from './types.js'
+
+const key = (opts?: ConsentOptions): string => opts?.storageKey ?? CONSENT_KEY
+
+const parse = (raw: string | null | undefined): ConsentRecord | null => {
+  if (raw == null || raw === '') {
+    return null
+  }
+  try {
+    const value = JSON.parse(raw) as unknown
+
+    return value != null && typeof value === 'object' ? value as ConsentRecord : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Bring a stored record up to the current shape.
+ *
+ * A record with no `v` was written before the essential category existed, when it was implicitly
+ * always granted. The visitor DID choose; upgrading in place honours that choice, where treating
+ * the record as unusable would re-prompt everyone who has ever visited.
+ */
+export const migrateConsent = (raw: ConsentRecord | null): ConsentRecord | null =>
+  raw == null ? null
+    : raw.v === CONSENT_SCHEMA_VERSION ? raw
+      : { ...raw, [CONSENT_ESSENTIAL]: true, v: CONSENT_SCHEMA_VERSION }
+
+const fromCookie = (name: string): string | null => {
+  if (typeof document === 'undefined') {
+    return null
+  }
+  const parts = `; ${document.cookie}`.split(`; ${name}=`)
+
+  return parts.length === 2 ? parts.pop()?.split(';').shift() ?? null : null
+}
+
+/**
+ * What this browser has already chosen, or null.
+ *
+ * localStorage first and the cookie second, because that is the order the widget this generalises
+ * used and the two can disagree: a visitor who cleared site data but kept cookies still has an
+ * answer, and asking them again would be wrong.
+ */
+export const readConsent = (opts?: ConsentOptions): ConsentRecord | null => {
+  const name = key(opts)
+  let raw: string | null = null
+  try {
+    raw = typeof localStorage !== 'undefined' ? localStorage.getItem(name) : null
+  } catch { /* private modes and blocked storage both throw; the cookie may still answer */ }
+
+  return migrateConsent(parse(raw) ?? parse(fromCookie(name)))
+}
+
+/**
+ * Record the choice in both places.
+ *
+ * Two stores rather than one because neither is reliable alone: localStorage is cleared by "clear
+ * site data" while the cookie survives it, and the cookie is refused where third-party storage is
+ * blocked while localStorage may not be.
+ */
+export const writeConsent = (record: ConsentRecord, opts?: ConsentOptions): void => {
+  const name = key(opts)
+  const value = JSON.stringify({ ...record, v: CONSENT_SCHEMA_VERSION })
+  try {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.setItem(name, value)
+    }
+  } catch { /* the cookie below is the fallback */ }
+
+  if (typeof document === 'undefined') {
+    return
+  }
+  const days = opts?.cookieDays ?? CONSENT_COOKIE_DAYS
+  const expires = new Date(Date.now() + days * 24 * 60 * 60 * 1000).toUTCString()
+  const domain = opts?.cookieDomain != null ? `;domain=${opts.cookieDomain}` : ''
+  // `SameSite=Lax` is stated rather than left to the browser default, which differs between them.
+  // This cookie is never sent cross-site on purpose — it records a preference, not a session.
+  document.cookie = `${name}=${value};expires=${expires};path=/;SameSite=Lax${domain}`
+}
+
+export const clearConsent = (opts?: ConsentOptions): void => {
+  const name = key(opts)
+  try {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.removeItem(name)
+    }
+  } catch { /* nothing to remove if storage was never available */ }
+  if (typeof document !== 'undefined') {
+    document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/`
+  }
+}