consentos/README.md

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:

1. Set ADMIN_BOOTSTRAP_TOKEN in .env to a strong random value (openssl rand -hex 32)
2. Restart the API
3. 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"}'
4. Unset or rotate ADMIN_BOOTSTRAP_TOKEN once 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:

1. You may not provide it to third parties as a hosted or managed service
2. 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.