@cookiecrumbs-eu/mcp 0.7.0

package/dist/config/src/export.js

@@ -0,0 +1,130 @@
+/** Every key of an export record (schema_registry `export_record` v1), always present, sorted. */
+export const EXPORT_RECORD_KEYS = [
+    'ac_string',
+    'categories',
+    'client_nonce',
+    'client_ts',
+    'collection',
+    'country',
+    'environment',
+    'event_type',
+    'gcm_state',
+    'id',
+    'language',
+    'occurred_at',
+    'prev_hash',
+    'record_hash',
+    'redacted',
+    'redaction_prev_hash',
+    'regime',
+    'regime_rules_version',
+    'sdk_version',
+    'services',
+    'site_id',
+    'subject_id',
+    'tc_string',
+    'texts_hash',
+    'ua_class',
+    'version_id',
+    'version_number',
+];
+/** Column order of `consent_csv` (schema_registry `export_csv` v1). */
+export const CSV_COLUMNS = [
+    'occurred_at',
+    'id',
+    'event_type',
+    'subject_id',
+    'version_number',
+    'version_id',
+    'texts_hash',
+    'language',
+    'country',
+    'regime',
+    'regime_rules_version',
+    'categories',
+    'services',
+    'gcm_state',
+    'collection',
+    'tc_string',
+    'ac_string',
+    'client_ts',
+    'sdk_version',
+    'client_nonce',
+    'prev_hash',
+    'record_hash',
+    'redacted',
+    'redaction_prev_hash',
+];
+const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * JSON with object keys sorted bytewise at every level and no whitespace. Unlike canonJson this
+ * accepts numbers (export records carry ints) and drops `undefined` members like JSON.stringify.
+ */
+export function stableStringify(value) {
+    if (value === null || value === undefined)
+        return 'null';
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? JSON.stringify(value) : 'null';
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (Array.isArray(value))
+        return '[' + value.map(stableStringify).join(',') + ']';
+    if (typeof value === 'object') {
+        const obj = value;
+        const parts = [];
+        for (const k of Object.keys(obj).sort(byCodeUnit)) {
+            if (obj[k] === undefined)
+                continue;
+            parts.push(JSON.stringify(k) + ':' + stableStringify(obj[k]));
+        }
+        return '{' + parts.join(',') + '}';
+    }
+    throw new Error('stableStringify: unsupported value ' + typeof value);
+}
+/** One `records.jsonl` line (without the trailing `\n`): every export key present, null when absent. */
+export function recordLine(record) {
+    const full = {};
+    for (const k of EXPORT_RECORD_KEYS)
+        full[k] = record[k] === undefined ? null : record[k];
+    return stableStringify(full);
+}
+/** Parses `records.jsonl` (blank lines ignored); throws with the 1-based line number on bad JSON. */
+export function parseRecordsJsonl(text) {
+    const out = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].replace(/\r$/, '');
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch (e) {
+            throw new Error(`records.jsonl line ${i + 1}: ${e.message}`);
+        }
+    }
+    return out;
+}
+/** RFC 4180: quote when the value contains `,`, `"`, `\n` (or `\r`); double embedded quotes. */
+export function csvEscape(value) {
+    return /[",\n\r]/.test(value) ? '"' + value.replace(/"/g, '""') + '"' : value;
+}
+function csvCell(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (typeof v === 'boolean')
+        return v ? 'true' : 'false';
+    if (typeof v === 'string')
+        return csvEscape(v);
+    if (typeof v === 'number' || typeof v === 'bigint')
+        return String(v);
+    return csvEscape(stableStringify(v));
+}
+/** One CSV row (without the trailing `\n`) in CSV_COLUMNS order; JSON columns use stableStringify. */
+export function toCsvRow(record) {
+    return CSV_COLUMNS.map((c) => csvCell(record[c])).join(',');
+}
+/** The CSV header line (without the trailing `\n`). */
+export const CSV_HEADER = CSV_COLUMNS.join(',');

package/dist/config/src/index.js

@@ -0,0 +1,16 @@
+export * from "./schema.js";
+export * from "./defaults.js";
+export * from "./lint.js";
+export * from "./theme.js";
+export * from "./regimes.js";
+export * from "./canon.js";
+export * from "./verify.js";
+export * from "./export.js";
+export * from "./declaration.js";
+export * from "./webhooks.js";
+export * from "./rules.js";
+import { BannerConfigSchema } from "./schema.js";
+/** Identity helper for cookiecrumbs.config.ts files: validates and returns the config. */
+export function defineConfig(config) {
+    return BannerConfigSchema.parse(config);
+}

package/dist/config/src/lint.js

@@ -0,0 +1,139 @@
+import { BannerConfigSchema, TEXT_KEYS } from "./schema.js";
+import { contrast } from "./theme.js";
+import { TRANSLATIONS } from "./defaults.js";
+export { contrast };
+/** Regimes whose model is opt-in (consent before any non-essential storage). */
+const OPT_IN_REGIMES = ['eu_optin', 'uk_pecr', 'ch_fadp', 'br_lgpd', 'ca_qc'];
+// --- WCAG contrast -------------------------------------------------
+function channel(c) {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+}
+export function luminance(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    return 0.2126 * channel((n >> 16) & 255) + 0.7152 * channel((n >> 8) & 255) + 0.0722 * channel(n & 255);
+}
+/**
+ * Legal + schema lint. Errors block publishing (the SQL private.lint_config applies the same
+ * codes and messages); warnings and infos are advisory.
+ */
+export function lintConfig(input, context = {}) {
+    const issues = [];
+    const parsed = BannerConfigSchema.safeParse(input);
+    if (!parsed.success) {
+        for (const e of parsed.error.issues) {
+            issues.push({ code: 'schema', severity: 'error', path: e.path.join('.'), message: e.message });
+        }
+        return { ok: false, issues };
+    }
+    const c = parsed.data;
+    const push = (code, severity, path, message) => issues.push({ code, severity, path, message });
+    const regimes = c.regions.regimes;
+    const enabled = (r) => !!regimes[r]?.enabled;
+    const necessary = c.categories.find((x) => x.key === 'necessary');
+    if (!necessary)
+        push('necessary_missing', 'error', 'categories', 'A locked "necessary" category is required.');
+    else if (!necessary.locked || !necessary.default)
+        push('necessary_not_locked', 'error', 'categories.necessary', 'The necessary category must be locked and on.');
+    const keys = new Set();
+    c.categories.forEach((cat, i) => {
+        if (keys.has(cat.key))
+            push('duplicate_category', 'error', `categories.${i}.key`, `Duplicate category "${cat.key}".`);
+        keys.add(cat.key);
+        if (cat.key !== 'necessary' && cat.locked)
+            push('locked_non_necessary', 'error', `categories.${i}.locked`, 'Only the necessary category may be locked.');
+    });
+    // Any enabled opt-in regime forbids pre-ticked non-essential categories (phase 1 checked eu_optin only).
+    if (OPT_IN_REGIMES.some(enabled)) {
+        c.categories.forEach((cat, i) => {
+            if (cat.key !== 'necessary' && cat.default)
+                push('default_on_non_necessary', 'error', `categories.${i}.default`, `"${cat.key}" cannot be on by default under an opt-in regime (GDPR Art. 4(11), EDPB 05/2020).`);
+        });
+    }
+    if (!c.languages.includes(c.default_lang))
+        push('no_default_lang', 'error', 'default_lang', 'The default language must be one of the enabled languages.');
+    const usOptout = enabled('us_optout');
+    const impliedDismiss = !!c.behaviour.implied_dismiss;
+    for (const lang of c.languages) {
+        const t = c.texts[lang];
+        if (!t) {
+            push('missing_text', 'error', `texts.${lang}`, `No texts for language "${lang}".`);
+            continue;
+        }
+        for (const k of TEXT_KEYS) {
+            if (!t[k] || !t[k].trim())
+                push('missing_text', 'error', `texts.${lang}.${k}`, `"${k}" is empty for "${lang}".`);
+        }
+        if (t.body && t.body.trim().length < 40)
+            push('short_body', 'warning', `texts.${lang}.body`, 'The first-layer text is very short; say what cookies are used for.');
+        if (usOptout && !(t.do_not_sell || '').trim())
+            push('us_link_text_missing', 'error', `texts.${lang}.do_not_sell`, `"do_not_sell" is empty for "${lang}"; a "Do Not Sell or Share" link is required under CCPA/CPRA (Cal. Civ. Code § 1798.135).`);
+        if (impliedDismiss && !(t.close_refuses || '').trim())
+            push('implied_dismiss_text_missing', 'error', `texts.${lang}.close_refuses`, `"close_refuses" is empty for "${lang}"; visitors must be told that closing counts as refusing (GDPR Art. 7(2), EDPB 05/2020).`);
+        const ct = c.category_texts[lang] ?? {};
+        for (const cat of c.categories) {
+            if (!ct[cat.key])
+                push('missing_text', 'error', `category_texts.${lang}.${cat.key}`, `No name/description for "${cat.key}" in "${lang}".`);
+        }
+    }
+    for (const [host, cat] of Object.entries(c.block)) {
+        if (!keys.has(cat))
+            push('block_unknown_category', 'error', `block.${host}`, `Category "${cat}" does not exist.`);
+    }
+    // Regions: the fallback must be usable; overrides must point at an enabled regime.
+    if (!enabled(c.regions.fallback))
+        push('fallback_disabled', 'error', 'regions.fallback', `Fallback regime "${c.regions.fallback}" is not enabled; enable it or choose an enabled regime.`);
+    for (const [cc, r] of Object.entries(c.regions.overrides ?? {})) {
+        if (!enabled(r))
+            push('regime_unknown_override', 'error', `regions.overrides.${cc}`, `Override for "${cc}" points to regime "${r}", which is not enabled.`);
+    }
+    const ct = contrast(c.theme.text, c.theme.background);
+    if (ct < 4.5)
+        push('contrast_text', 'error', 'theme.text', `Text on background is ${ct.toFixed(2)}:1; 4.5:1 is required (WCAG 1.4.3).`);
+    const cb = contrast(c.theme.button_text, c.theme.button);
+    if (cb < 4.5)
+        push('contrast_button', 'error', 'theme.button_text', `Button text on button is ${cb.toFixed(2)}:1; 4.5:1 is required.`);
+    const cbb = contrast(c.theme.button, c.theme.background);
+    if (cbb < 3)
+        push('contrast_button_bg', 'warning', 'theme.button', `Buttons are hard to see on the background (${cbb.toFixed(2)}:1).`);
+    // ---- the wording -----------------------------------------------------------
+    // The built-in body names what is processed, what for, that data may reach countries without an
+    // adequate level of protection, and that consent is voluntary and revocable. A much shorter text
+    // probably says none of that. A warning, not a blocker: a short custom text can be perfectly legal
+    // and refusing to publish it would be us overruling the operator's own lawyer.
+    for (const lang of c.languages) {
+        const body = (c.texts[lang]?.body ?? '').trim();
+        const built = TRANSLATIONS[lang]?.texts.body;
+        if (built && body.length < built.length * 0.45) {
+            push('body_below_standard', 'warning', `texts.${lang}.body`, `This text is much shorter than the wording CookieCrumbs ships, which names what is processed, what it is used for, that data may reach countries without an adequate level of protection, and that consent is voluntary. Use the built-in wording to restore it.`);
+        }
+    }
+    // ---- the site's own pages -------------------------------------------------
+    // An imprint is a legal requirement wherever this ships (in Germany and Austria it is explicit), and
+    // a consent notice is often the only chrome a visitor sees before deciding. It is required.
+    const url = (v) => !!v && /^https?:\/\/\S+$/i.test(v.trim());
+    if (!url(c.links?.imprint)) {
+        push('imprint_missing', 'error', 'links.imprint', 'An imprint address is required. Add it under Legal; it is shown in the footer of every banner.');
+    }
+    // A data protection notice is as much a requirement for an EU banner as the imprint: the consent
+    // text refers to processing the notice must describe (GDPR Arts. 12-13).
+    if (!url(c.links?.privacy)) {
+        push('privacy_link_missing', 'error', 'links.privacy', 'A data protection notice is required. Add its address under Legal; it is linked in the footer of every banner next to the imprint.');
+    }
+    if (!['floating', 'link'].includes(c.behaviour.reopen_control))
+        push('reopen_disabled', 'error', 'behaviour.reopen_control', 'Visitors must be able to reopen the banner (GDPR Art. 7(3)).');
+    // Quebec Law 25 s. 9.1: the settings control is presented as confidentiality settings.
+    if (enabled('ca_qc') && regimes.ca_qc?.settings_label !== 'default') {
+        for (const lang of c.languages) {
+            const t = c.texts[lang];
+            if (t && !(t.confidentiality_settings || '').trim())
+                push('qc_settings_text_missing', 'warning', `texts.${lang}.confidentiality_settings`, `"confidentiality_settings" is empty for "${lang}"; under Quebec Law 25 (s. 9.1) the settings control is presented as confidentiality settings.`);
+        }
+    }
+    // Advanced Consent Mode without scan evidence (public.gcm_verification): informational, never blocking.
+    if (c.consent_mode.enabled && c.consent_mode.mode === 'advanced' && context.gcm_verified === false)
+        push('gcm_advanced_unverified', 'info', 'consent_mode.mode', 'Advanced Consent Mode is on but the last completed scan observed no gtag consent default call on this site; run a scan after installing the tag.');
+    if (c.layout === 'headless')
+        push('headless_layout', 'info', 'layout', 'Headless layout renders no banner; your own UI must offer Accept all, Reject all and settings with equal prominence.');
+    return { ok: !issues.some((i) => i.severity === 'error'), issues };
+}

package/dist/config/src/regimes.js

@@ -0,0 +1,62 @@
+/** Human labels used by the dashboard, CLI and tests. */
+export const REGIME_LABELS = {
+    eu_optin: 'EU / EEA opt-in (GDPR + ePrivacy)',
+    uk_pecr: 'United Kingdom (UK GDPR + PECR)',
+    us_optout: 'United States opt-out (CCPA/CPRA and state laws)',
+    ch_fadp: 'Switzerland (FADP)',
+    br_lgpd: 'Brazil (LGPD)',
+    ca_qc: 'Quebec, Canada (Law 25)',
+};
+/** The 27 EU member states plus the three EEA/EFTA countries (IS, LI, NO). */
+export const EU_EEA_COUNTRIES = [
+    'AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL',
+    'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE',
+    'IS', 'LI', 'NO',
+];
+/**
+ * region_rule_sets v3 `countries` map. `CA` resolves to `ca_qc` on purpose: the IP tables the platform
+ * uses (`private.ip_country`, geoip-lite country mode) have no province granularity, Law 25 binds anyone
+ * doing business in Quebec, and its opt-in model also satisfies PIPEDA. Sites that do not want Quebec
+ * rules for the rest of Canada set `regions.overrides.CA`.
+ */
+export const COUNTRY_REGIMES = {
+    ...Object.fromEntries(EU_EEA_COUNTRIES.map((c) => [c, 'eu_optin'])),
+    GB: 'uk_pecr',
+    US: 'us_optout',
+    CH: 'ch_fadp',
+    BR: 'br_lgpd',
+    CA: 'ca_qc',
+};
+/** region_rule_sets v3 `subdivisions` map (ISO 3166-2), consulted before `countries`. */
+export const SUBDIVISION_REGIMES = {
+    'CA-QC': 'ca_qc',
+};
+/** Regime definitions of region_rule_sets v2 (`regimes`). */
+export const REGIME_RULES = {
+    eu_optin: { model: 'opt_in', expiry_months_max: 13 },
+    uk_pecr: { model: 'opt_in', expiry_months_max: 13 },
+    us_optout: { model: 'opt_out', expiry_months_max: 12 },
+    ch_fadp: { model: 'opt_in', expiry_months_max: 13 },
+    br_lgpd: { model: 'opt_in', expiry_months_max: 13 },
+    ca_qc: { model: 'opt_in', expiry_months_max: 13 },
+};
+export const REGION_RULES_VERSION = 3;
+export const REGIME_FALLBACK = 'eu_optin';
+/**
+ * Mirrors public.resolve_regime(code) on region_rule_sets v3: an ISO 3166-2 subdivision (`CA-QC`) is
+ * looked up first, then the ISO 3166-1 alpha-2 country, then the rule set's fallback (`eu_optin`) for
+ * null / unknown input. Case-insensitive.
+ */
+export function defaultRegimeForCountry(country) {
+    if (!country)
+        return REGIME_FALLBACK;
+    const code = country.trim().toUpperCase();
+    return SUBDIVISION_REGIMES[code] ?? COUNTRY_REGIMES[code.split('-')[0]] ?? REGIME_FALLBACK;
+}
+/** Maximum consent lifetime the runtime applies for a regime (months): 12 for us_optout, else 13. */
+export function expiryCapMonths(regime) {
+    return REGIME_RULES[regime]?.expiry_months_max ?? 13;
+}
+export function isRegime(x) {
+    return typeof x === 'string' && x in REGIME_RULES;
+}

package/dist/config/src/rules.js

@@ -0,0 +1,90 @@
+/**
+ * The shared rules reference: one citation knowledge base for the MCP tools
+ * (`rules_reference`, `check_first_layer`, `explain_classification`), the dashboard Issue
+ * detail page and the CLI.
+ *
+ * Rules of the file (contracts.md, phase 6):
+ *   - every entry cites a primary source with a URL and a publication date;
+ *   - `quote` is either the *verified* wording of that source or `null` — never a paraphrase
+ *     dressed up as a quotation. Entries without a verified quote carry a `summary` in our
+ *     own words;
+ *   - nothing here is legal advice. Callers must keep showing the
+ *     "This is not a legal assessment" line.
+ */
+import reference from '../rules_reference.json' with { type: 'json' };
+const REFERENCE = reference;
+/** Compliance issue codes — mirrors the `compliance_issues_code_check` constraint. */
+export const ISSUE_KINDS = [
+    'preconsent_tracker',
+    'unclassified_tracker',
+    'install_unverified',
+    'domain_unverified',
+    'no_screenshots',
+    'consent_mode_mismatch',
+    'reject_not_layer1',
+    'version_missing_texts',
+    'declaration_stale',
+    'a11y_violation',
+];
+/** Every code `lintConfig()` can emit. The test asserts this list against src/lint.ts. */
+export const LINT_CODES = [
+    'block_unknown_category',
+    'body_below_standard',
+    'contrast_button',
+    'contrast_button_bg',
+    'contrast_text',
+    'default_on_non_necessary',
+    'duplicate_category',
+    'fallback_disabled',
+    'gcm_advanced_unverified',
+    'headless_layout',
+    'implied_dismiss_text_missing',
+    'imprint_missing',
+    'locked_non_necessary',
+    'missing_text',
+    'necessary_missing',
+    'necessary_not_locked',
+    'no_default_lang',
+    'privacy_link_missing',
+    'qc_settings_text_missing',
+    'regime_unknown_override',
+    'reopen_disabled',
+    'schema',
+    'short_body',
+    'us_link_text_missing',
+];
+/** The full reference, frozen. */
+export const RULES_REFERENCE = REFERENCE;
+export const RULES = REFERENCE.rules;
+export const RULE_TOPICS = REFERENCE.topics;
+/** The line every surface must keep next to a citation. */
+export const NOT_LEGAL_ADVICE = 'This is not a legal assessment.';
+const byId = new Map(REFERENCE.rules.map((r) => [r.id, r]));
+/** One rule by its stable id, or null. */
+export function ruleById(id) {
+    return byId.get(id) ?? null;
+}
+/** Every rule filed under a topic, in file order. Unknown topics return []. */
+export function rulesFor(topic) {
+    return REFERENCE.rules.filter((r) => r.topic === topic);
+}
+/**
+ * Every rule that explains an issue kind (`compliance_issues.code`) or a lint code.
+ * Both vocabularies live in `applies_to`, so one accessor serves the Issue detail page and
+ * the legal lint alike.
+ */
+export function citationsFor(issueKind) {
+    return REFERENCE.rules.filter((r) => r.applies_to.includes(issueKind));
+}
+/** Free-text search over source, summary, quote and paragraph — used by the MCP `rules_reference` tool. */
+export function searchRules(query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [...REFERENCE.rules];
+    return REFERENCE.rules.filter((r) => [r.id, r.topic, r.source, r.summary, r.quote ?? '', r.paragraph ?? '', ...r.applies_to].join(' ').toLowerCase().includes(q));
+}
+/** A one-line rendering, e.g. `EDPB … (para. 8) — https://…`. Never invents a quote. */
+export function formatCitation(rule) {
+    const where = rule.paragraph ? ` (${rule.paragraph})` : '';
+    return `${rule.source}${where} — ${rule.source_url}`;
+}