DEV Community: ProtoConsent

An open API for composable privacy extensions

ProtoConsent — Sun, 26 Apr 2026 01:52:24 +0000

How browser extensions can query the user's consent state via a standard protocol

The problem: privacy tools that can't talk to each other

The browser extension ecosystem has ad blockers, cookie managers, fingerprint protectors, and VPN clients. Each makes decisions about user privacy independently. None of them knows what the others are doing, and none of them knows what the user actually wants at the purpose level.

If an ad blocker wants to know whether the user has allowed analytics on a given site, there's no way to ask. If a cookie manager wants to check whether the user has denied ads, it has to implement its own consent model. Every privacy extension reinvents the same wheel, and the user has to configure each one separately.

A read-only consent API

ProtoConsent exposes an inter-extension API that lets other browser extensions query the user's consent state. The protocol uses chrome.runtime.sendMessage with ProtoConsent's extension ID as the target. The API is read-only: consumer extensions can read preferences but never modify them.

Two message types are supported:

Capabilities discovery: the consumer asks what the provider supports (protocol version, available purposes).
Consent query: the consumer asks for the user's consent state on a specific domain. The response contains all six purposes as booleans, plus the active profile name.

A consent query looks like this:

// Query
{ "type": "protoconsent:query", "domain": "example.com" }

// Response
{
  "type": "protoconsent:response",
  "domain": "example.com",
  "purposes": {
    "functional": true,
    "analytics": false,
    "ads": false,
    "personalization": true,
    "third_parties": false,
    "advanced_tracking": false
  },
  "profile": "balanced"
}

One domain per request. No bulk queries. The response contains only the fixed six-purpose schema, a profile name, and a version string.

Trust on first use

The API is disabled by default. The user must explicitly enable it in ProtoConsent's settings. Even then, each consumer extension must be individually approved.

On first contact from an unknown extension, ProtoConsent stores a pending authorization request and responds with a need_authorization error. The user can then approve or deny the extension from the settings UI. This is a TOFU (Trust on First Use) model: no extension gets access without the user's explicit approval.

Approved extensions are stored in an allowlist.
Denied extensions are moved to a denylist. Future messages from denied extensions are silently dropped, giving no signal that ProtoConsent is active.
The pending queue is capped at 10 entries to prevent flooding.
A global cooldown limits new unknown extension IDs to 3 per minute.
Approved extensions are rate-limited to 10 requests per minute.

Why this matters

Privacy tools today are silos. Each one has its own model of what the user wants, its own configuration UI, and its own enforcement rules. The result is duplication, inconsistency, and cognitive load for the user.

An open consent API changes this. A cookie manager could check whether the user has allowed analytics before deciding what to clean. A content blocker could query purpose preferences before applying its rules. A fingerprint protector could adapt its behavior based on whether the user has denied advanced tracking on a given site.

The user configures their preferences once, in one place. Other tools read those preferences and adapt. That's composable privacy: tools that work together instead of side by side.

Security by design

The protocol is designed to be safe by default:

Read-only: there is no code path from external messages to storage writes or rule changes.
Sender verification: sender.id is provided by the browser and cannot be forged.
No intrusive prompts: authorization requests are queued silently and reviewed at the user's discretion. No popup windows, no clickjacking vectors.
Observable: all inter-extension events (successes, errors, rate limits) are visible in the extension's log, timestamped and color-coded.

Cross-browser compatibility

The protocol works identically on Chrome and Firefox. Both support chrome.runtime.onMessageExternal and runtime sender verification. ProtoConsent omits externally_connectable from the manifest, giving open access on both browsers. Security is enforced at runtime (opt-in, allowlist, rate limiting), not at the manifest level.

Try it

A minimal test consumer extension is available in the source repository under examples/test-consumer/. It sends capabilities queries, consent queries, invalid inputs, and rate-limit tests, and logs responses in a popup panel.

ProtoConsent is free and open source (GPL-3.0+). The inter-extension protocol is part of the draft specification and open to feedback.

How ProtoConsent answers consent banners without touching the DOM

ProtoConsent — Sun, 26 Apr 2026 01:49:16 +0000

A declarative approach to CMP auto-response: cookie injection, not click simulation

The banner problem

Consent management platforms (CMPs) are used by millions of websites to show consent banners. When you visit a site, the CMP checks for a cookie that records your consent. If it doesn't find one, it shows the banner.

Most tools that deal with banners take one of two approaches: they simulate clicks on banner buttons (fragile, depends on DOM structure) or they block the CMP script entirely (breaks sites that check __tcfapi for vendor compliance). Both are reactive: they wait for something to appear, then act.

The ProtoConsent approach: declare, don't interact

ProtoConsent takes a different path. Instead of interacting with the banner after it appears, it writes the consent cookie that the CMP expects to find before the CMP script even loads.

When a page loads, a content script runs at document_start (before any page JavaScript executes). It reads the user's purpose preferences and a set of CMP signature templates from extension storage. For each applicable CMP, it generates a valid consent cookie by replacing purpose placeholders with the user's choices and writes it to the document. When the CMP script loads a moment later, it reads its own cookie, sees a valid consent record, and skips the banner entirely.

The user's preferences are enforced without ever touching the DOM, without simulating clicks, and without waiting for the banner to render.

CMP signatures

Each supported CMP is described by a JSON signature that specifies the cookie name, a value template with purpose placeholders, and optional CSS selectors for the banner. A simplified example:

{
  "cookie": [{
    "name": "consent_status",
    "template": "groups=1:1,2:{analytics},3:{personalization},4:{ads}"
  }],
  "format": { "allow": "1", "deny": "0" },
  "selector": "#consent-banner"
}

The content script replaces {analytics}, {personalization}, and {ads} with 1 or 0 based on the user's choices. The result is a cookie that the CMP treats as a valid consent record.

ProtoConsent currently supports signatures for dozens of CMPs, including both widely-deployed frameworks and platform-specific consent implementations. The full list is maintained in the source repository.

Three layers of response

Cookie injection alone doesn't cover every case. Some CMPs use server-side consent mechanisms, some use localStorage, and some load asynchronously. ProtoConsent uses three complementary layers:

Layer 1: Cookie injection - writes the consent cookie with the user's purpose choices. This is the primary mechanism and works for the majority of CMPs.
Layer 2: Cosmetic CSS - injects CSS rules that hide known banner selectors (display: none !important). This is a safety net for CMPs where cookie injection is late or incomplete, and the only option for CMPs with server-side consent mechanisms.
Layer 3: Scroll unlock - removes scroll-lock classes and inline styles that CMPs apply to prevent scrolling until consent is given. A MutationObserver watches for re-locking attempts for 10 seconds.

IAB TCF v2.2 TC String generation

For CMPs that read the euconsent-v2 cookie (the IAB Transparency and Consent Framework standard), ProtoConsent generates a valid TC String. The user's six purpose preferences are mapped to TCF's 24 purpose IDs, and the result is encoded as a base64url bitfield following the TCF v2.2 specification.

This means sites that check the IAB standard for consent status see a properly formatted consent record that reflects the user's actual choices, not a blanket "accept all" or "deny all".

Purpose-level control, not binary

Unlike most consent tools that treat banners as "accept" or "reject", ProtoConsent maps its six purposes to each CMP's specific categories. If you allow analytics but deny ads, the generated cookie reflects exactly that. The CMP sees a nuanced consent record, and the site can load analytics scripts while keeping ad trackers disabled.

This is possible because the signature system knows how each CMP maps purposes to cookie values. The extension doesn't need to understand the CMP's UI; it just needs to speak its data format.

Cookie cleanup and privacy

Injected cookies are deleted after 5 seconds. CMPs read their cookies synchronously during initialization (the first 1-2 seconds of page load). Once the CMP has read the cookie and decided not to show the banner, the cookie is no longer needed. Deleting it reduces HTTP overhead on subsequent requests and minimizes the consent cookie's lifetime.

Each page visit generates a fresh random UUID (via crypto.randomUUID()) for cookies that require one, so consent cookies cannot be used to correlate visits across navigations.

Comparison with other approaches

	ProtoConsent	Click-based extensions	Content blockers
Mechanism	Cookie injection at `document_start`	DOM interaction (simulate clicks)	Block CMP script entirely
Timing	Before CMP loads (preventive)	After banner renders (reactive)	Before CMP loads (preventive)
Banner appears	No	Briefly	No
CMP reads preferences	Yes (from injected cookie)	Yes (via its own UI)	No (CMP never loads)
Purpose-level control	Yes (per-purpose values)	Varies (most are all-or-nothing)	No (binary block/allow)
Breakage risk	Low (CMP sees valid consent)	Medium (DOM changes break selectors)	High (consent wall, missing API)

Limitations

This approach has honest limitations:

Server-signed cookies: some CMPs use server-generated tokens that cannot be replicated client-side. ProtoConsent falls back to cosmetic hiding on these sites.
Server-side consent: some platforms handle consent entirely via server endpoints. Cosmetic fallback applies.
Site-specific tokens: some CMPs use site-specific identifiers that cannot be templated. Cosmetic fallback applies.
Consent walls: sites that tie consent to a paywall are not circumvented by design.
TC String vendor sections: the generated TC String has empty vendor consent sections. CMPs that check for specific vendor IDs may not fully accept it, though in practice CMPs read the purpose bits.

One piece of the puzzle

CMP auto-response handles the consent interface layer. ProtoConsent also enforces purpose choices at the network level, blocking requests associated with denied purposes via declarativeNetRequest before they leave the browser. A conditional GPC signal (Sec-GPC) is sent per site when privacy-relevant purposes are denied, carrying legal weight under CCPA/CPRA. Together, they form a layered system: the banner is pre-empted, the requests are blocked, and the site receives the user's preference as a standards-based signal.

ProtoConsent is free and open source (GPL-3.0+). See the source code on GitHub.

A .well-known file for website privacy declarations

ProtoConsent — Sun, 26 Apr 2026 01:46:22 +0000

How websites can declare their data practices in a machine-readable format

The idea

Most websites have a privacy policy. Most people don't read them. What if a website could declare its data practices in a machine-readable format that a browser extension could read, display, and compare against the user's preferences?

That's what .well-known/protoconsent.json does. It follows the same pattern as security.txt (RFC 9116) and .well-known/change-password: a static file at a standard path that tools can discover and consume automatically.

What it looks like

A minimal declaration for a blog that uses privacy-friendly analytics:

{
  "protoconsent": "0.2",
  "purposes": {
    "functional": {
      "used": true,
      "legal_basis": "legitimate_interest"
    },
    "analytics": {
      "used": true,
      "legal_basis": "consent",
      "providers": ["Privacy-friendly Analytics"],
      "retention": { "type": "fixed", "value": 30, "unit": "days" }
    }
  }
}

The file declares which of ProtoConsent's six purposes the site uses, under what legal basis, with which providers, and for how long data is retained. Purposes not included are treated as "not declared" (the site makes no claim). Setting "used": false explicitly states a purpose is not active.

The six purposes

The declaration uses the same purpose taxonomy as the ProtoConsent extension:

functional - core site functionality (login, cart, preferences)
analytics - usage measurement and reporting
ads - advertising and ad targeting
personalization - content personalization based on user behavior
third_parties - embedded third-party services (maps, videos, social widgets)
advanced_tracking - cross-site tracking, fingerprinting, user profiling

For each purpose, the site can declare: whether it's used, the legal basis (aligned with GDPR Article 6), providers involved, data sharing scope, and retention period.

A fuller example

An e-commerce site with ads, analytics, and third-party sharing:

{
  "protoconsent": "0.2",
  "last_updated": "2026-04-13",
  "purposes": {
    "functional": {
      "used": true,
      "legal_basis": "contractual",
      "retention": { "type": "session" }
    },
    "analytics": {
      "used": true,
      "legal_basis": "consent",
      "providers": ["Analytics provider"],
      "retention": { "type": "fixed", "value": 2, "unit": "years" }
    },
    "ads": {
      "used": true,
      "legal_basis": "consent",
      "providers": ["Ad network", "Retargeting pixel"],
      "sharing": "third_parties",
      "retention": { "type": "fixed", "value": 6, "unit": "months" }
    },
    "personalization": {
      "used": true,
      "legal_basis": "consent",
      "retention": { "type": "until_withdrawal" }
    },
    "third_parties": {
      "used": true,
      "legal_basis": "consent",
      "sharing": "third_parties",
      "retention": { "type": "fixed", "value": 2, "unit": "years" }
    },
    "advanced_tracking": { "used": false }
  },
  "data_handling": {
    "storage_region": "eu",
    "international_transfers": true
  },
  "links": {
    "policy": "https://shop.example.com/privacy",
    "rights": "https://shop.example.com/privacy#your-rights"
  }
}

How the extension uses it

When you visit a site that serves a .well-known/protoconsent.json, the ProtoConsent extension fetches and validates it. The declared practices are displayed in a side panel alongside the user's own preferences, using Consent Commons icons for each purpose.

This creates a two-column view: what the site says it does (declaration) and what the user wants (preferences). Users can see at a glance whether a site's stated practices align with their choices.

Self-assertion, not certification

The declaration is a voluntary, self-asserted transparency signal. It does not change how the extension enforces user preferences. Publishing a protoconsent.json file does not prove actual technical behavior: a site could declare "ads": { "used": false } while still loading ad trackers. The extension always enforces the user's own profile.

Think of it like security.txt: it's a machine-readable way for sites to say "here's what we do" that tools can consume. Trust comes from the declaration being public, inspectable, and comparable against observed behavior.

Complementary to existing standards

GPC (Sec-GPC): signals user preference (browser to site). The declaration signals site practices (site to browser). They are complementary directions.
ProtoConsent SDK: enables dynamic interaction (page queries extension). The declaration enables static discovery (extension reads site). A site can use one, both, or neither.
Consent Commons: the purpose categories and legal basis values align with the Consent Commons taxonomy.

Get started

Publishing a declaration takes a few minutes:

Generate: use the online generator to create your file interactively.
Validate: check your file with the online validator or the GitHub Action for CI/CD.
Publish: place the file at /.well-known/protoconsent.json on your domain. For GitHub Pages, add a .nojekyll file so the .well-known directory is served.
List your site: add it to the public directory of sites with declarations.

For the full specification, see protoconsent-well-known.md on GitHub. The JSON Schema (v0.2) is also available for programmatic validation.

Purpose-based consent: a missing layer in the browser

ProtoConsent — Sun, 26 Apr 2026 01:43:34 +0000

Why organizing privacy choices around purposes, not vendors, changes everything

The problem with consent today

There is no browser-level place where a user can say "I allow analytics but not ads on this site" and have it enforced consistently. Privacy choices today are scattered across per-site dialogs, each with different language, different categories, and different defaults. The result is not informed consent - it is consent fatigue.

Existing tools sit at two extremes. Content blockers operate on domains and filter lists: effective, but blunt. Consent management platforms (CMPs) operate per site and per vendor: flexible for the site, opaque for the user. There is no browser-level layer in between where you can express intent by purpose and have it enforced consistently across sites.

Why purpose-based

ProtoConsent organizes decisions around purposes of data use: functional, analytics, ads, personalization, third-party services, and advanced tracking. Not around vendors, cookies, or domains.

Purpose is the only abstraction that connects three things simultaneously:

Regulation: major privacy frameworks organize consent around purpose limitation. GDPR, CCPA/CPRA, LGPD, PIPL, PIPA, and APPI all use purpose as the fundamental unit.
Human comprehension: people think "I don't want ads tracking me", not "I don't want requests to doubleclick.net". Purpose maps to how users actually reason about their choices.
Viable enforcement: purposes can be mapped to domain categories and filter rules that browser extension APIs can enforce at the network level.

A vendor-based model would fragment decisions across hundreds of entities. A cookie-based model would ignore network-level tracking. Purpose sits at the right level of abstraction.

Why browser-level

ProtoConsent places enforcement in the browser, not in the site or in a backend:

No delegation to sites: enforcement does not depend on each site honoring preferences. The browser blocks requests before they leave your device.
No backend: no central server, no accounts, no cloud sync. All state is local.
Consistency: the same choice applies the same way across sites, rather than being re-negotiated per banner.

The browser is the only place where you can block requests, emit privacy signals like GPC, and show the user what happened, all without introducing new remote points of control.

Express, enforce, observe

ProtoConsent starts from a single premise: consent is only meaningful if the user can express it in understandable terms, enforce it technically, and observe its effects. If any of the three is missing, the system fails.

Express: per-site profiles and purpose toggles let you say "on this site, allow analytics but deny ads" from a single popup.
Enforce: the browser blocks requests associated with denied purposes before they leave your device. A conditional GPC signal is sent per site, with legal weight under CCPA/CPRA.
Observe: blocked request counters, a real-time log, and per-domain purpose attribution show you exactly what enforcement does.

This creates a feedback loop: the user decides, the browser enforces, the user sees the result. Consent becomes a process, not a single click.

Enforcement is a means, not an end

ProtoConsent uses curated blocklists to enforce user choices, but blocking is not the goal: it is the mechanism that makes consent meaningful. The current core set is built from public blocklists, organized by purpose, with cross-source validation and an explicit safelist. Path-based precision (blocking google.com/pagead/ instead of all of google.com) prioritizes correctness over exhaustiveness.

Optional extended lists provide broader coverage with curated third-party sources for users who want it, without changing the core model.

Voluntary site cooperation

ProtoConsent supports two optional ways for websites to participate:

Site declarations: a website publishes a .well-known/protoconsent.json file declaring its purposes, legal bases, and providers. The extension displays it alongside user preferences. It is a transparency signal, not enforcement evidence.
SDK: websites can query the user's consent state per purpose and adapt their behavior accordingly. The SDK is read-only and returns null if no extension is present.

Both paths are optional. ProtoConsent works without any site integration. Sites that cooperate add transparency, not a requirement.

What ProtoConsent is not

Not a full ad blocker: its goal is purpose-based consent enforcement, not exhaustive tracking coverage.
Not a consent management platform: it does not manage consent on behalf of sites or negotiate with vendors.
Not a VPN or anonymity tool: browser-level enforcement cannot prevent server-side processing or offline correlation.
Not a legal compliance tool: it provides technical mechanisms for consent, not legal adjudication.

ProtoConsent adds a layer that didn't exist: a personal consent control panel in the browser, organized around purposes, that can work alongside the tools you already use.

Try it

ProtoConsent is free and open source (GPL-3.0+ for the extension, MIT for the SDK). Available on the Edge Add-ons Store. Try the live demo, or read the developer guide to integrate your site.

Source: github.com/ProtoConsent/ProtoConsent