feat: initial public release

ConsentOS — a privacy-first cookie consent management platform. Self-hosted, source-available alternative to OneTrust, Cookiebot, and CookieYes. Full standards coverage (IAB TCF v2.2, GPP v1, Google Consent Mode v2, GPC, Shopify Customer Privacy API), multi-tenant architecture with role-based access, configuration cascade (system → org → group → site → region), dark-pattern detection in the scanner, and a tamper-evident consent record audit trail. This is the initial public release. Prior development history is retained internally. See README.md for the feature list, architecture overview, and quick-start instructions. Licensed under the Elastic Licence 2.0 — self-host freely; do not resell as a managed service.
2026-04-13 14:20:15 +00:00
commit fbf26453f2
341 changed files with 62807 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,182 @@
+<p align="center">
+  <img src="assets/brand/logo-lockup.svg" alt="ConsentOS" width="260">
+</p>
+
+<h1 align="center">Privacy infrastructure for the modern web</h1>
+
+<p align="center">
+  A self-hosted, multi-tenant cookie consent management platform.<br>
+  Source-available alternative to OneTrust, Cookiebot and CookieYes.
+</p>
+
+<p align="center">
+  <a href="https://github.com/consentos/consentos/actions"><img src="https://img.shields.io/github/actions/workflow/status/consentos/consentos/ci.yml?branch=master&label=CI&style=flat-square" alt="CI status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/licence-Elastic--2.0-1B3C7C?style=flat-square" alt="Elastic Licence 2.0"></a>
+  <a href="https://consentos.dev"><img src="https://img.shields.io/badge/site-consentos.dev-2C6AE4?style=flat-square" alt="consentos.dev"></a>
+</p>
+
+---
+
+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](https://github.com/jkwakman/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](https://docs.astral.sh/uv/)
+
+### Setup
+
+```bash
+# 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
+
+```bash
+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:
+
+```bash
+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](https://github.com/jkwakman/Open-Cookie-Database) — a community-maintained catalogue of 2,200+ cookie patterns used for auto-categorisation during scans. To update:
+
+```bash
+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](CONTRIBUTING.md) for setup instructions, coding standards, and PR guidelines. We follow [Conventional Commits](https://www.conventionalcommits.org/) and write everything in British English.
+
+## Security
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md). Please do not open public issues for security reports.
+
+## Licence
+
+ConsentOS is licensed under the [Elastic Licence 2.0 (ELv2)](LICENSE) — 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](https://github.com/jkwakman/Open-Cookie-Database) under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+See the [LICENSE](LICENSE) file for the full licence text and copyright notice.