bd465008e5
* fix(banner): bridge blocker state between loader and bundle
``consent-loader.js`` and ``consent-bundle.js`` are built as two
separate rollup IIFEs, so each inlines a private copy of
``blocker.ts``. The loader's copy is the one that actually matters
— it installs the ``document.cookie`` / ``Storage.prototype.setItem``
/ ``MutationObserver`` proxies, and those proxies close over the
loader's private ``acceptedCategories`` set and its
``blockedScripts`` queue.
The bundle used to ``import { updateAcceptedCategories } from './blocker'``
and call it from ``handleConsent``. That updated the **bundle's**
dead-end copy of the blocker module — a different ``Set`` object in
a different scope from the one the proxies read — so after the user
granted consent the loader's proxies stayed stuck on
``Set(['necessary'])``, any non-necessary cookie write kept being
silently dropped, and the loader's queue of blocked scripts was
never released.
Fix by exposing the loader's live ``updateAcceptedCategories`` on
``window.__consentos._updateBlocker`` right after
``installBlocker()``, and replacing the bundle's dead-end import
with a helper that calls through the bridge. The bundle no longer
imports from ``./blocker`` at all; rollup tree-shakes the bundle's
copy out, so ``consent-bundle.js`` gets slightly smaller.
Tests (``__tests__/blocker-bridge.test.ts``) cover:
* Bridge is called with the exact accepted list.
* Bridge is forwarded verbatim (no slug filtering).
* Missing bridge logs a warning and doesn't throw.
* Missing ``window.__consentos`` logs a warning and doesn't throw.
``vi.hoisted`` seeds ``window.__consentos`` before banner.ts's
module-level ``init()`` runs so the import-time IIFE doesn't throw
on the empty global.
* fix(banner): sweep disallowed cookies + storage on consent update
When the loader runs it now proactively deletes any pre-existing
cookies (and localStorage / sessionStorage keys) that classify into
a category the visitor hasn't consented to. Fixes the common case
of an ``_ga`` that slipped through before the loader was installed
— e.g. on a host page that loads the loader with ``async`` or
places another tracker above it in ``<head>`` — sitting there
forever because the blocker's only defence was a setter proxy on
future writes.
Sweep semantics:
- Runs on every ``updateAcceptedCategories`` call (consent narrowed
→ the just-revoked categories' cookies are wiped) plus an
explicit call from the loader's "no consent yet" branch (initial
visit with pre-existing trackers from elsewhere).
- Only deletes cookies / keys whose classifier hits a known
pattern (``_ga``, ``_fbp``, ``intercom-*`` etc. — same lists as
the proxied setters). Unknown / unclassified cookies are left
alone: we can't attribute them and won't risk clobbering
first-party session state.
- ``_consentos_*`` is always preserved.
- For cookies, we don't know the original ``domain`` / ``path``
(``document.cookie`` doesn't expose them), so we fire deletes
against every plausible domain variant — bare hostname, leading
``.``, and every parent domain walked up from the left. Covers
the GA "set on ``.example.com`` from a subdomain page" case
without over-deleting.
- Deletions bypass the proxied setter and go directly through the
cached ``originalCookieDescriptor`` captured before the proxy was
installed, so the blocker doesn't eat its own expiry writes.
- Storage access is wrapped in ``safeStorage`` — sandboxed /
cross-origin iframes that throw on ``window.localStorage`` are
skipped rather than crashing the loader.
Tests in ``__tests__/blocker.test.ts`` cover: non-consented analytics
cookies are deleted, consented ones are preserved, unknown cookies
survive, ``_consentos_*`` is untouched, revoking a category after
seeding new cookies triggers a follow-up sweep, and localStorage
cleanup follows the same rules. 6 new cases, 373 passing total in
the banner suite.
Privacy infrastructure for the modern web
A self-hosted, multi-tenant cookie consent management platform.
Source-available alternative to OneTrust, Cookiebot and CookieYes.
ConsentOS gives you a single <script> tag to embed on your site and a self-hosted dashboard to manage everything behind it: consent collection, cookie blocking, scanning, compliance checking, and audit trails. The full surface — banner, API, scanner, admin UI — is in this repository, with no SaaS lock-in.
Why ConsentOS
- Privacy by design, not by default. Consent is given, not assumed. Auto-blocking is on by default; visitors don't get tracked until they opt in.
- Standards-complete. IAB TCF v2.2, GPP v1 (six US state sections), Google Consent Mode v2, GPC, Shopify Customer Privacy API.
- Yours to host. Source-available under the Elastic Licence 2.0 — you can self-host indefinitely, modify freely, and run it on your own infrastructure.
- Built for compliance teams. Rule-based compliance checks for GDPR, CNIL, CCPA/CPRA, ePrivacy and LGPD, plus a tamper-evident consent record audit trail.
- Multi-tenant from day one. Organisations, sites, role-based access. Configuration cascades System → Org → Site Group → Site → Region.
Features
- Consent banner — ~2KB loader + ~26KB bundle, gzipped, rendered in a Shadow DOM root for total style isolation
- Auto-blocking — intercepts script creation, cookie writes, and storage API calls until consent is granted; releases per-category
- Cookie scanner — Playwright-driven crawl with auto-categorisation against the Open Cookie Database (2,200+ patterns)
- Dark pattern detection — flags pre-ticked boxes, missing reject buttons, button asymmetry, scroll-based dismissal
- Compliance engine — rules for GDPR, CNIL, CCPA/CPRA, ePrivacy, LGPD with severity scoring
- Configuration cascade — defaults → org → site group → site → regional override
- Display modes — bottom banner, top banner, overlay modal, corner popup, inline
- Consent withdrawal — persistent floating button so visitors can change their mind (GDPR Art. 7(3))
- i18n-ready banner — translations API per site, locale auto-detection
- GeoIP-aware — region-specific consent modes (opt-in for EU, opt-out for US-CA, etc.)
Architecture
┌─────────────────────────────────────────────────────┐
│ Client Browser │
│ ┌─────────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Consent │ │ Script │ │ Banner UI │ │
│ │ Loader (2KB)│→ │ Blocker │ │ (Shadow DOM) │ │
│ └──────┬──────┘ └──────────┘ └───────────────┘ │
│ │ TCF v2.2 · GCM v2 · GPP v1 · GPC │
└─────────┼───────────────────────────────────────────┘
│
▼
┌─────────────────────┐ ┌──────────────────────┐
│ FastAPI Backend │ │ Scanner Service │
│ · Config API │ │ · Playwright crawler│
│ · Consent API │ │ · Auto-categoriser │
│ · Compliance API │ │ · Celery worker │
└─────────┬───────────┘ └──────────────────────┘
│
┌─────┴──────┐
│ PostgreSQL │ Redis (cache + queue)
└────────────┘
Quick start
Prerequisites
- Docker and Docker Compose v2.15+
- Node.js 20+ and npm
- Python 3.12+ and uv
Setup
# Clone and configure
git clone https://github.com/consentos/consentos.git
cd consentos
cp .env.example .env
# Start the dev environment
make up
# Run migrations and seed cookie categories
make seed
| Service | URL |
|---|---|
| API docs | http://localhost:8000/docs |
| Admin UI | http://localhost:5173 |
The admin UI dog-foods the banner script at http://localhost:5173/banner/consent-loader.js. In production you'd publish those files to a CDN and point CDN_BASE_URL at it.
Bootstrapping the first organisation
The POST /api/v1/organisations/ endpoint is gated behind a static admin token by default. To create your initial organisation:
- Set
ADMIN_BOOTSTRAP_TOKENin.envto a strong random value (openssl rand -hex 32) - Restart the API
curl -X POST http://localhost:8000/api/v1/organisations/ -H "X-Admin-Bootstrap-Token: <your-token>" -H "Content-Type: application/json" -d '{"name": "Acme", "slug": "acme"}'- Unset or rotate
ADMIN_BOOTSTRAP_TOKENonce your org is created — leaving it set means anyone with the value can keep creating tenants.
Running tests
make test-infra-up # Start test PostgreSQL + Redis
make test # Run API tests
make test-cov # With coverage
make test-infra-down # Tear down
Banner and admin UI tests:
cd apps/banner && npm test
cd apps/admin-ui && npm test
Project structure
consentos/
├── apps/
│ ├── api/ # FastAPI backend (Python)
│ ├── scanner/ # Playwright cookie scanner (Python)
│ ├── banner/ # Consent banner script (TypeScript)
│ └── admin-ui/ # Admin dashboard (React + TypeScript)
├── assets/brand/ # Logo, palette, brand guidelines
├── helm/ # Kubernetes Helm chart
├── sdks/ # Mobile SDKs (iOS, Android)
├── docker-compose.yml # Development environment
└── Makefile
Technology
| Layer | Stack |
|---|---|
| API | Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic |
| Scanner | Python 3.12, Playwright, Celery |
| Banner | TypeScript, Rollup, Shadow DOM |
| Admin UI | React 19, Vite, shadcn/ui, TailwindCSS, TanStack Query |
| Database | PostgreSQL 16 |
| Cache | Redis 7 |
| Infra | Docker Compose, Kubernetes (Helm), Ansible |
Known cookies database
ConsentOS ships with the Open Cookie Database — a community-maintained catalogue of 2,200+ cookie patterns used for auto-categorisation during scans. To update:
curl -L https://raw.githubusercontent.com/jkwakman/Open-Cookie-Database/master/open-cookie-database.csv \
-o apps/api/data/open-cookie-database.csv
make seed
Contributing
See CONTRIBUTING.md for setup instructions, coding standards, and PR guidelines. We follow Conventional Commits and write everything in British English.
Security
To report a vulnerability, see SECURITY.md. Please do not open public issues for security reports.
Licence
ConsentOS is licensed under the Elastic Licence 2.0 (ELv2) — a source-available licence.
You may use, copy, distribute, and modify the software freely, with two restrictions:
- You may not provide it to third parties as a hosted or managed service
- You may not circumvent any licence key functionality
This means: self-host it on your own infrastructure as much as you like; offer it to your customers as part of a wider product; modify it to your heart's content. You just can't resell ConsentOS itself as a SaaS — that's how the project sustains itself.
The known cookies database (apps/api/data/open-cookie-database.csv) is sourced from the Open Cookie Database under CC BY 4.0.
See the LICENSE file for the full licence text and copyright notice.