npm - @ecomconsult/consentkit - Versions diffs - 0.3.5 → 0.4.0 - Mend

@ecomconsult/consentkit 0.3.5 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md CHANGED Viewed

@@ -44,7 +44,7 @@ Four ways to add ConsentKit to a site, from simplest to most integrated.
 |---|---|---|---|
 | 1 | **Script tags** — copy `src/` to your server, three `<script>` tags in `<head>` | Any site you control | [Quickstart below](#quickstart--script-tags) |
 | 2 | **npm** — `npm install @ecomconsult/consentkit` | Bundled apps, React | [Quickstart below](#quickstart--npm) |
-| 3 | **WordPress plugin** — copy the plugin folder to `wp-content/plugins/` | WordPress / WooCommerce | [`plugins/wordpress/consentkit/`](plugins/wordpress/consentkit/) |
+| 3 | **WordPress plugin** — copy the plugin folder to `wp-content/plugins/`; rewrites static tracker tags server-side | WordPress / WooCommerce | [`plugins/wordpress/consentkit/`](plugins/wordpress/consentkit/) |
 | 4 | **Google Tag Manager** — import the container, trigger tags on consent events | Sites already running GTM | [`integrations/gtm/README.md`](integrations/gtm/README.md) |
 ```sh
@@ -66,6 +66,7 @@ must come first and should not be deferred.
 ```html
 <script src="/consentkit/src/ck-core.js"></script>
 <script src="/consentkit/src/ck-locales.js"></script><!-- optional: extra languages -->
+<script src="/consentkit/src/ck-ui-branding.js"></script><!-- optional: logo / attribution -->
 <script src="/consentkit/src/ck-ui.js"></script>
 <script>
   ConsentKit.init({
@@ -188,6 +189,9 @@ Pass any subset to `init()`. Nested objects merge with the defaults.
 | `consentTtlDays` | `number` | `365` | Lifetime of the stored decision |
 | `integrations.gcm` | `boolean` | `true` | Google Consent Mode v2 signals |
 | `integrations.gtmDataLayer` | `boolean` | `true` | Push consent events to `window.dataLayer` |
+| `blocking.mode` | `"known" \| "strict"` | `"known"` | `strict` also holds back unknown third-party scripts and iframes — see [Strict mode](#strict-mode) |
+| `blocking.allow` | `string[]` | `[]` | Hosts strict mode must never intercept. Matched by suffix, so `partner.com` also covers `cdn.partner.com` |
+| `hostdb` | `Record<string, Category>` | — | Extra `host: category` pairs merged into the tracker database, applied before the initial scan. SaaS mode fills this from the service; `ConsentKit._extendHostDb()` does the same at any later point |
 | `cookieTable` | `CkCookieTableEntry[]` | `[]` | Declared cookies, listed per category in the panel |
 `cookieTable` entries:
@@ -279,6 +283,11 @@ Iframes use `data-src`, which is applied once the category is allowed:
 `data-ck` accepts any category name: `functional`, `analytics`, `marketing`.
+> On WordPress this markup is applied **automatically, server-side**, for every
+> tracker in the built-in database — see "Server-side markup" below. Manual
+> markup is still needed for trackers the database does not know (your own
+> domain, an unlisted vendor) and for inline snippets.
 ### Automatic blocking
 Scripts injected at runtime are intercepted without any markup. ConsentKit
@@ -301,6 +310,130 @@ and DoubleClick.
 Because the patches install at parse time, `ck-core.js` must load before any
 tracker — put it first in `<head>` and do not add `defer`.
+`<iframe src>` is covered by the same three patches, and a blocked frame keeps
+its URL in `data-src` until its category is granted.
+### Extending the tracker database
+The built-in host list is a snapshot, not an oracle. `_extendHostDb()` merges
+extra `host: category` pairs into it at runtime:
+```js
+ConsentKit._extendHostDb({
+  'analytics.vendor.example': 'analytics',
+  'pixel.partner.example': 'marketing'
+});
+```
+Matching is the same as for built-in entries — a bare domain also covers its
+subdomains — and an override wins over the shipped classification for the same
+host. Categories outside `necessary | functional | analytics | marketing` and
+malformed hostnames are ignored; the call returns how many pairs were accepted.
+It works both **before and after** `init()`. Calling it afterwards does not
+re-examine anything already inserted (a script that has loaded cannot be
+unloaded), but every later insertion is classified against the extended map.
+In SaaS mode this is automatic: `ck-saas.js` applies `config.hostdb` from the
+service *before* it calls `init()`, and again when a background revalidation
+brings a changed table. At release time `node tools/sync-hostdb.mjs` bakes the
+same public table into `src/ck-core.js`, so inline blocks, the npm package and
+the WordPress plugin get it too.
+### Strict mode
+By default ConsentKit blocks what it **recognises**. `blocking.mode: 'strict'`
+inverts that for third parties: before consent, any `<script src>` or
+`<iframe src>` pointing at a host that is not same-site is intercepted, whether
+or not the tracker database has ever heard of it.
+```js
+ConsentKit.init({
+  blocking: { mode: 'strict', allow: ['widgets.partner.example'] }
+});
+```
+Four things are never intercepted:
+1. **Same-site URLs** — the page's own host, its subdomains, and anything
+   sharing its registrable domain. The check is deliberately conservative: when
+   the answer is unclear it says same-site, because wrongly blocking a
+   first-party asset breaks the site.
+2. **`blocking.allow`** — your own list, matched by suffix.
+3. **The built-in allowlist**, readable as `ConsentKit._baseAllow`: asset CDNs
+   (`cdn.jsdelivr.net`, `unpkg.com`, `cdnjs.cloudflare.com`, `code.jquery.com`,
+   `fonts.googleapis.com`, `fonts.gstatic.com`) and things a page is unusable
+   without (`js.stripe.com`, `pay.google.com`, `checkout.creem.io`,
+   `hcaptcha.com`, and reCAPTCHA — scoped to `www.google.com/recaptcha` and
+   `www.gstatic.com/recaptcha`, not to those hosts at large).
+4. **Known `necessary` / `functional` hosts** already granted, which keep their
+   real category rather than being swept up as marketing.
+Anything else is filed under **`marketing`** — the strictest category — and
+comes back only when the visitor accepts marketing.
+**Read this before switching it on.** Strict mode will block third-party code
+your site needs and that ConsentKit has no way to recognise as necessary: a
+booking widget, a map, a review embed, a payment provider that is not on the
+list. Turn it on, load the site with `?ck_debug=1`, and read the "Blocked until
+consent" list in the panel — entries the engine held back only because of strict
+mode are labelled `strict`. Everything there that the page genuinely needs
+belongs in `blocking.allow`.
+Two limits are worth stating plainly:
+* **Dynamic insertions only**, exactly as for known trackers. A tag written
+  straight into the HTML starts its request before ConsentKit runs (see below).
+  The WordPress plugin's server-side rewrite currently marks up *known* trackers
+  only; extending it to strict mode is recorded as a follow-up in SPEC.md.
+* **Strict starts when the config does.** The mode is read from `config`, so in
+  SaaS mode nothing is blocked strictly until the config has arrived. Blocking
+  of *known* trackers still begins at parse time, as always.
+### Static tags: what the browser cannot catch
+Runtime injection is covered by the patches above. A tracker tag written
+**directly into the HTML** is not: the parser starts that request before the
+first line of `ck-core.js` runs. The gap was measured (debt Д9: request at
+14 ms, our script at 18 ms) and it is negative — no client-side technique
+closes it. Such tags need either manual markup, or a server that rewrites them
+before the page is sent.
+### Server-side markup (WordPress plugin)
+The WordPress plugin does exactly that, and it is **on by default** since 0.3.5.
+While the page is generated, it rewrites tracker tags in the finished HTML:
+```html
+<!-- what the theme wrote -->
+<script src="https://mc.yandex.ru/metrika/tag.js"></script>
+<!-- what the browser receives -->
+<script type="text/plain" data-ck="analytics"
+        data-ck-src="https://mc.yandex.ru/metrika/tag.js"></script>
+```
+`<iframe src>` of a known host becomes `data-ck` + `data-src` with `src`
+removed. The categories come from the same HOST_DB/PATH_DB as the browser
+engine: `tools/export-hostdb.mjs` generates
+`plugins/wordpress/consentkit/includes/hostdb.php` from `src/ck-core.js`, and
+`test/hostdb.test.mjs` fails if the two drift.
+What it skips: ConsentKit's own assets, tags carrying `data-ck-ignore`, tags
+already marked up by hand, inline scripts (there is no URL to defer), the GTM
+container, and anything inside comments, `<pre>` or `<textarea>`. On any error
+the page is returned unchanged.
+The `<pre>` / `<textarea>` skip keeps the *source text* byte-identical, which is
+what a page documenting a tracker snippet needs. It does not keep such a tag
+alive: the browser parses `<pre><script src=…>` as a real script element
+whatever the server did, so the runtime engine may still intercept it. Caching plugins are compatible and get the
+already-rewritten HTML, because the rewrite happens at the PHP level before the
+page is cached.
+Outside WordPress the same idea applies to any server-side template: emit the
+`type="text/plain" data-ck` form directly, as in "Manual markup" above.
 ## Google Consent Mode v2
 With `integrations.gcm` (default), the core pushes `consent: default` with every
@@ -348,18 +481,23 @@ external requests. Rebuild them with `tools/build-inline.mjs` (see
 [`tools/README.md`](tools/README.md)); each block's header records the exact
 command that produced it.
-ConsentKit 0.3.5, rebuilt 2026-09-04, uncompressed — gzip on the server cuts
-this roughly three- to fourfold. Every block includes the attribution line;
-`--no-branding` takes ~200 bytes back off:
+ConsentKit 0.4.0, rebuilt 2026-09-05, uncompressed — gzip on the server cuts
+this roughly three- to fourfold. Every block includes the branding extension
+and the attribution line; `--no-branding` drops both the code and the config
+and takes **~24 KB** back off:
-| Block | Languages | Bytes |
-|---|---|---|
-| `ready/en-bar.txt` | en | 111,664 |
-| `ready/ru-bar.txt` | ru, ro, en | 113,285 |
-| `ready/ru-box.txt` | ru, ro, en | 113,300 |
-| `ready/ru-box-right.txt` | ru, ro, en | 113,309 |
-| `ready/ru-modal.txt` | ru, ro, en | 113,293 |
-| `ready/eu-bar.txt` | 34 languages | 161,939 |
+| Block | Languages | Bytes | gzip | `--no-branding` |
+|---|---|---|---|---|
+| `ready/en-bar.txt` | en | 134,969 | 40,519 | 110,907 |
+| `ready/ru-bar.txt` | ru, ro, en | 136,590 | 41,315 | 112,508 |
+| `ready/ru-box.txt` | ru, ro, en | 136,605 | 41,320 | 112,523 |
+| `ready/ru-box-right.txt` | ru, ro, en | 136,614 | 41,326 | 112,526 |
+| `ready/ru-modal.txt` | ru, ro, en | 136,598 | 41,318 | 112,514 |
+| `ready/eu-bar.txt` | 34 languages | 185,244 | 59,665 | 161,182 |
+0.4.0 adds roughly 16.1 KB over 0.3.6: iframe interception, strict mode
+(same-site detection, the allowlists, the public-suffix table) and the
+extensible tracker database.
 Size is driven almost entirely by the bundled languages: `en` and `ru` are
 built into the UI and cost nothing extra, while layout, position, theme and
@@ -540,13 +678,19 @@ has been verified and what has not.
 - `dataLayer` event trace for consent restore, upgrade and withdrawal.
 - npm entry points and TypeScript types: syntax and import smoke tests in Node
   without a DOM.
-- PHP files of the WordPress plugin pass `php -l` on 7.4 and 8.5.
+- PHP files of the WordPress plugin pass `php -l` on 7.4, 8.3 and 8.5.
+- The server-side rewriting engine has its own suite of 61 cases
+  (`plugins/wordpress/consentkit/tests/rewrite.test.php`), green on PHP 7.4,
+  8.3 and 8.5. It is a plain PHP CLI script, so it runs outside `npm test`.
 ### Not verified — read before production use
-- **The WordPress plugin has never run on a live WordPress install.** It passes
-  linting and review, but no activation, settings round-trip, theme conflict or
-  multisite behaviour has been observed in a real installation.
+- **The WordPress plugin has been verified on a live install, but only one.**
+  It was run on WordPress 7.1 / PHP 8.3 in Docker (activation, settings
+  round-trip, shortcode, uninstall, server-side markup end to end). The declared
+  floor of WordPress 6.0 / PHP 7.4 has not been exercised live — the PHP files
+  pass `php -l` and the rewriting test suite on 7.4, 8.3 and 8.5 — and no theme
+  conflict or multisite behaviour has been observed.
 - **The GTM container has never been through a real import.** The JSON is valid
   and structurally modelled on the documented export format, but Tag Manager has
   not accepted it in practice; some field names (notably GA4 config

package/npm/core.mjs CHANGED Viewed

@@ -28,6 +28,9 @@ export const {
   rejectAll,
   withdraw,
   show,
-  hide
+  hide,
+  // v0.4.0 (§1.3): merging service overrides into the tracker database is part
+  // of the public surface, so it must be reachable as a named import too.
+  _extendHostDb
 } = ConsentKit;
 export { ConsentKit };

package/npm/index.cjs CHANGED Viewed

@@ -69,7 +69,10 @@ var hasDom = typeof document !== 'undefined' && typeof window !== 'undefined';
 if (hasDom) {
   // 2. Locales — optional language packs.
   try { require('../src/ck-locales.js'); } catch (e) { /* optional */ }
-  // 3. UI — touches `document` at module scope, browser only.
+  // 3. Branding — optional, and before the UI: it registers itself on
+  //    ConsentKit._uiExtensions and must be there before the first mount().
+  try { require('../src/ck-ui-branding.js'); } catch (e) { /* optional */ }
+  // 4. UI — touches `document` at module scope, browser only.
   try { require('../src/ck-ui.js'); } catch (e) { /* best effort */ }
 }

package/npm/index.d.ts CHANGED Viewed

@@ -88,6 +88,20 @@ export interface CkIntegrationsConfig {
   gtmDataLayer?: boolean;
 }
+/** v0.4.0 (§2). How much the blocking engine holds back before consent. */
+export interface CkBlockingConfig {
+  /**
+   * `'known'` (default) blocks what the tracker database recognises.
+   * `'strict'` additionally intercepts EVERY third-party `<script src>` and
+   * `<iframe src>` that is not same-site, not in `allow`, not in the built-in
+   * allowlist (`ConsentKit._baseAllow`) and not an already-granted
+   * necessary/functional host. Interceptions are filed under `marketing`.
+   */
+  mode?: 'known' | 'strict';
+  /** Hosts strict mode must never intercept. Suffix match: `p.com` covers `cdn.p.com`. */
+  allow?: string[];
+}
 /** One declared cookie, shown under its category in the preferences panel. */
 export interface CkCookieTableEntry {
   name: string;
@@ -109,6 +123,15 @@ export interface CkConfig {
   /** Lifetime of the stored decision, in days. Default `365`. */
   consentTtlDays?: number;
   integrations?: CkIntegrationsConfig;
+  /** v0.4.0. Default `{ mode: 'known', allow: [] }`. */
+  blocking?: CkBlockingConfig;
+  /**
+   * v0.4.0 (§1.3). Extra `host: category` pairs merged into the tracker
+   * database. `init()` applies them before its initial scan, so scripts
+   * already in the markup are classified against them. In SaaS mode the
+   * service supplies this; `_extendHostDb()` does the same at any later point.
+   */
+  hostdb?: Record<string, CkCategory>;
   cookieTable?: CkCookieTableEntry[];
 }
@@ -141,6 +164,50 @@ export interface ConsentKitApi {
   show(): void;
   /** Dispatches `ck:ui:close`. */
   hide(): void;
+  /**
+   * v0.4.0 (§1.3). Merges `{ host: category }` into the runtime tracker
+   * database and returns how many pairs were accepted. Matching follows the
+   * built-in table: a bare domain also covers its subdomains, and an override
+   * wins over the shipped classification for the same host.
+   *
+   * Safe before AND after `init()`. Afterwards, nothing already inserted is
+   * re-examined — a script that has loaded cannot be unloaded — but every
+   * later insertion is classified against the extended map.
+   */
+  _extendHostDb(map: Record<string, CkCategory>): number;
+  /**
+   * v0.4.0 (§2). The built-in strict-mode allowlist, as hosts plus a few
+   * `host/path` entries (reCAPTCHA). A copy: mutating it changes nothing.
+   */
+  readonly _baseAllow: string[];
+  /** The category the engine would assign to a URL, or `null` if unknown. */
+  _categoryForUrl(url: string): CkCategory | null;
+  /** What is currently held back, host+path only — never a query string. */
+  _blocked(): CkBlockedEntry[];
+}
+/** One entry of `ConsentKit._blocked()`. */
+export interface CkBlockedEntry {
+  host: string;
+  path: string;
+  /** `'script'`, `'iframe'`, … */
+  kind: string;
+  category: CkCategory | null;
+  /** `'engine'` — intercepted by the patches; `'markup'` — marked up by hand. */
+  origin: 'engine' | 'markup';
+  /** v0.4.0. True when strict mode held this back, i.e. the host is unknown. */
+  strict: boolean;
+  /**
+   * v0.4.0. `false` when the category was granted but the element still never
+   * loaded — typically a script created and given a `src` without ever being
+   * appended, which `applyConsentToDom()` cannot reach. Such entries stay in
+   * the report after consent precisely so they can be diagnosed.
+   */
+  revived: boolean;
 }
 declare const ConsentKit: ConsentKitApi;
@@ -156,6 +223,7 @@ export declare function rejectAll(): CkState;
 export declare function withdraw(): CkState;
 export declare function show(): void;
 export declare function hide(): void;
+export declare function _extendHostDb(map: Record<string, CkCategory>): number;
 declare global {
   interface Window {

package/npm/index.mjs CHANGED Viewed

@@ -3,7 +3,9 @@
  * re-exports the public API.
  *
  * Load order is contractual: ck-core.js (blocking starts at parse time) →
- * ck-locales.js (extra language packs) → ck-ui.js (Shadow DOM layer).
+ * ck-locales.js (extra language packs) → ck-ui-branding.js (optional logo /
+ * attribution extension, which must register before the UI mounts) →
+ * ck-ui.js (Shadow DOM layer).
  *
  * Only the core is DOM-optional. `src/ck-ui.js` touches `document` at module
  * scope, so it is imported dynamically behind a `typeof document` guard —
@@ -25,6 +27,13 @@ if (hasDom) {
     await import('../src/ck-locales.js');
   } catch (e) { /* locales are optional; ck-ui falls back to built-in en/ru */ }
+  // Optional branding extension. Before ck-ui.js on purpose: it registers
+  // itself on ConsentKit._uiExtensions and must be there before the first
+  // mount(). Absent, the UI simply draws no logo and no attribution line.
+  try {
+    await import('../src/ck-ui-branding.js');
+  } catch (e) { /* branding is optional; the UI renders without it */ }
   // Required in the browser, fatal in Node — hence the guard above.
   try {
     await import('../src/ck-ui.js');
@@ -42,6 +51,9 @@ export const {
   rejectAll,
   withdraw,
   show,
-  hide
+  hide,
+  // v0.4.0 (§1.3): merging service overrides into the tracker database is part
+  // of the public surface, so it must be reachable as a named import too.
+  _extendHostDb
 } = ConsentKit;
 export { ConsentKit };

package/npm/internal-stub.mjs CHANGED Viewed

@@ -28,7 +28,7 @@ export function undecidedState() {
  */
 export function createStub() {
   const stub = {
-    version: '0.3.5',
+    version: '0.4.0',
     config: {},
     init: function () { return undecidedState(); },
     allowed: function (cat) { return cat === 'necessary'; },
@@ -39,6 +39,12 @@ export function createStub() {
     show: function () {},
     hide: function () {},
     _categories: CATEGORIES.slice(),
+    // v0.4.0: the stub mirrors the real surface, so consumer code that calls
+    // these needs no branching when the core failed to attach.
+    _extendHostDb: function () { return 0; },
+    _baseAllow: [],
+    _categoryForUrl: function () { return null; },
+    _blocked: function () { return []; },
     _isStub: true
   };
   return stub;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ecomconsult/consentkit",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "GDPR cookie consent core with blocking engine, Shadow DOM UI and Google Consent Mode v2. Zero dependencies, no build step.",
   "repository": {
     "type": "git",