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.

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 replacement for dedicated ad blockers: its core goal is purpose-based consent enforcement. Enhanced Protection provides substantial blocking out of the box, but the focus is purpose attribution and user control.
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