Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

Quick Start

  • If you’re a user wanting to test the WEBCAT browser extension, check out For Users.
  • If you’re a site operator wanting to enroll your site or web application, check out For Developers.
  • If you’re a developer wanting to contribute to the WEBCAT browser extension or infrastructure, check out For Contributors.
  • If you want to learn about the WEBCAT architecture, check out Architecture.
  • If you want to learn about running WEBCAT infrastructure, check out For Infrastructure Operators.

Why WEBCAT Exists

TK

Concepts

Glossary

  • Transparency Log An append-only, publicly verifiable data structure that records signed statements (such as manifests) in a way that enables auditing, monitoring, and detection of mis-issuance or equivocation.

  • Sigsum A transparency system based on simple, auditable logs and explicit witness cosigning, designed to provide verifiable publication without relying on centralized certificate authorities.

  • Sigstore A signing and transparency ecosystem that binds signatures to identities derived from federated identity providers (e.g., OIDC), typically using short-lived certificates and public transparency logs.

  • Content Security Policy (CSP) A web security mechanism, expressed as an HTTP response header, that restricts the origins from which a web application may load resources such as scripts, styles, and workers.

  • Cooldown A time window (1 day during alpha stage; 7 days afterwards) during which an enrollment change for a given domain is monitorable, but still not applied and fully revertable.

Parties

  • Developers build a static web application that complies with the restrictions required for WEBCAT to operate securely. They publish enrollment information describing their signing identities and trust policy. For each release, they build the application, generate a manifest describing the release and its assets, sign it, and record it in a transparency log.

  • Website administrators who may also be developers, are responsible for publishing the web application, its enrollment information, and the corresponding manifest. They configure the web server to comply with parameters specified in the manifest, such as the default Content Security Policy and the default entry point (e.g., the index page). Website administrators are also responsible for enrolling their domain in the WEBCAT enrollment system and for signaling enrollment changes over time. In centralized deployments, website administrators and developers are typically the same entity.

  • Infrastructure operators such as the Freedom of the Press Foundation (FPF), run components of the WEBCAT enrollment system. The enrollment system is a distributed, consensus-based system; no single operator has unilateral control over its state or decisions.

  • End users install the WEBCAT browser extension. The extension updates automatically at startup and at regular intervals and operates transparently during normal browsing. Only in the event of validation errors may page loads be blocked, in which case the user is notified. No additional user interaction is required.

  • Auditors and monitors independently audit and monitor both the WEBCAT enrollment system and any transparency logs used by developers. They may notify developers or website administrators when relevant actions occur, such as new signatures being recorded in a transparency log or requests to modify a website’s enrollment information.

Getting Started

For Users

TK

For Site Operators

Site Enrollment

For Developers

App Requirements

CSP

Examples

We have tentatively ported a feww selected open-source web application to prove their potential compatibility with WEBCAT. No official support is provided, as such, administrators as discouraged from deploying them without prior testing, and understandinf that updates might be breaking, or require significant additional work.

TODO: remove the examples from the main WEBCAT repo and move them here. Update the command line from the old signing script to the new webcat-cli.

Test App

Jitsi

Element

Globaleaks

Bitwarden

Cryptpad

Architecture

This section describes WEBCAT’s system design and infrastructure.

Overview

Full architecture summary

Components

Enrollment Infrastructure

The WEBCAT enrollment infrastructure is a distributed system, designed to reduce censorship risks and avoid single points of trust or failure.

For sequence diagrams of the enrollment flow and oracle/validator communication, see here.

Key entities and behaviors

The chain consists of a number of nodes, each of whom may or may not be a consensus validator. Every node has a consensus key, but only some have non-zero voting power, designated by the application. Those nodes with non-zero voting power are called validators. Every node, regardless of whether it is a validator or not, is capable of accepting transactions for submission into a block, and serves a REST API for querying various aspects of the chain state, in addition to the default CometBFT API.

Validators are responsible for the liveness of the chain. Even if there are other non-voting nodes, the chain will not make progress without 2/3 of the validators participating. The entities operating a validator may or may not perform other services related to the chain, such as functioning as an admin or an oracle.

The chain is configured by a voting quorum of admins, each of whom has a unique admin key. This is an offline key which is only used to sign transactions approving changes to the chain’s configuration (i.e. voting parameters, registration quotas, validator set, oracle set, etc.).

The chain stores a canonical state which maps domains to enrollment manifest hashes. This state is updated by the action of oracles, which post signed observations of domains to the chain itself. The mechanism for triggering an oracle observation of a domain is external to the chain itself and oracles are separate entities which may be hosted on different infrastructure than chain nodes. This canonical state is internally stored by domain or subdomain in prefix-order, i.e. .com.example instead of example.com, to facilitate efficient prefix lookups of all subdomains. An API server for querying this state and other internal states of interest is hosted by the felidae binary: go to /snapshot for the current full snapshot, or (for example) to /snapshot/example.com for a filtered view showing the snapshot only for example.com and all its subdomains. Other endpoints are described where declared in crates/felidae/src/cli/start/query.rs.

When a domain owner wishes to enroll or unenroll their domain in the WEBCAT chain, they must interact with a frontend (not yet built) which will communicate with all known and reachable oracles and instruct them to render an observation of the /.well-known/webcat/enrollment.json file on their domain. Each oracle independently validates this file and submits a signed observation to the chain. Once a quorum of oracles has observed the same file hash, the chain inserts that hash into a pending queue on-chain which waits for a configured delay before applying that enrollment update to the canonical state. Any new updates abort pending updates in the queue, so that domain owners could be notified when their domain enters the pending queue and push a new update to revert any malicious enrollment modification.

All on-chain cryptographic keys with the exception of validator consensus keys are NIST P-256 ECDSA keypairs using SHA-256, to ensure compatibility with a wide variety of signing environments for oracles and admins. Additionally, care has been taken to ensure that the oracle transaction building code in particular can be run in a WASM environment, so that future iterations of oracles could be run in serverless Javascript environments, e.g. Cloudflare Workers.

Example Scenario

Nodes

  • The network consists of 3 authoritative nodes, each operated by a different semi-trusted organization.
  • Authoritative node identities (public keys) are hardcoded in the blockchain configuration.
  • Adding or replacing nodes requires either:
    • manual reconfiguration by all existing nodes, or
    • a consensus-based update mechanism approved by the network.
  • Non-authoritative (observer) nodes can sync and audit the blockchain but do not participate in consensus.
  • Consensus requires 2 out of 3 nodes, allowing tolerance for one offline or malicious participant.
  • Malicious updates require collusion by at least 2 nodes.

Enrollment

  • Enrollment requests can be submitted via a web interface hosted by authoritative nodes, or optionally by non-authoritative nodes which relay the transaction request.
  • The first receiving authoritative node performs integrity checks:
    • Verifies policy list consistency.
    • Fetches and inspects the domain (e.g., HTTP headers).
  • Upon successful validation, the node signs and broadcasts the transaction to its peers.
  • If ≥2/3 of nodes validate and sign the transaction, it is committed to the blockchain.

List Consensus

  • Each node maintains a local state mapping domains to their policy hash.
  • Every new block includes:
    • the hash of the current trust list state,
    • a timestamp, and
    • signatures from ≥2/3 of nodes.
  • The list hash and signatures form a verifiable consensus snapshot.
  • Any node (authoritative or not) can export the full list + consensus metadata.
  • This bundle is distributed via CDN.

Browser component (e.g. WEBCAT Extension)

  • The browser extension embeds the public keys of authoritative nodes.
  • Periodically fetches trust list updates from the CDN.
  • Verifies:
    • At least 2/3 valid node signatures.
    • The timestamp is newer than the last known update.
  • On success, the browser trusts and imports the new list.

Censorship considerations

  • Enrollment censorship requires ≥2 nodes to block a valid submission.
  • List publication censorship requires ≥2 nodes to omit entries.

CometBFT

CometBFT is the de facto library for building custom blockchains with consensus. It handles networking, cryptographic operations, and consensus, leaving transaction and block validation mostly to the application developer. The blockchain can be permissioned: nodes are manually authorized (or voted in, if implemented), so scalability issues and takeover risks are minimal or non-existent.

Feature Parity with WEBCAT Infra

The transparency logging requirement of WEBCAT Infra is dropped—here, the blockchain itself serves as a transparency log. Note: transparency logging is still required for manifest signatures and for Sigstore’s OIDC certificates.

Monitoring can be performed by any blockchain node that is not a validator. Non-validators can perform the same checks on the list state and verify domain consensus, enabling both:

  • Monitoring: e.g., a service that alerts domain owners when changes are initiated.
  • Auditing: independent verification of consensus and list state.

Ideal Scenario

Organizations like the Freedom of the Press Foundation, Tor Project, and others—ideally across different jurisdictions (e.g., Tor relay associations)—run validator nodes on low-cost VPSes or on-premises hardware (from ~$5/month). There is native support for using (cloud) HSMs if needed.

Each organization may offer a web interface for submission to their local node, secured with CAPTCHA or basic rate-limiting. The receiving node performs validation and broadcasts the transaction to the rest of the network.

Enrollment Preload List Building

At every finalized block, the current state of the preload list—agreed upon by a majority of validators—can be extracted and signed. Any node can then publish this list for the WEBCAT extension to consume.

The WEBCAT extension does not trust a specific node; instead, it verifies that:

  • There was valid consensus.
  • The current block height/timestamp is greater than the previous one.

Hacking / Censorship Scenario

To fake or force an enrollment operation, an attacker would need control of at least 3 out of 5 validator nodes (this threshold is configurable). The preload list cannot be forged or censored, as clients require a valid network consensus. Thus, only a majority of nodes (or the organizations behind them) could alter the list content.

Pros

  • No single point of failure; harder to censor
  • Lower operational cost (no HA or per-org redundancy needed)
  • Shared trust/liability across jurisdictions

Cons

  • Slightly more complex setup
  • Frontends must implement rate-limiting, or use alternatives like proof-of-work
  • Involves more parties to coordinate

Future Work

Extending the chain with non-breaking changes mostly involves updating the software. For example, implementing Tor-specific validation (if agreed upon) or testing alternate policies should be straightforward. Note that what is in the list (Sigstore, versus just public keys) does not influence the technical setup of this. There’s just the need to change the validatot function according to the schema we agree upon.

For Contributors

This section is for anyone contributing to WEBCAT development.

Enrollment Infrastructure

WEBCAT Infra Chain — the repository for the Rust enrollment infrastructure.

See the basic architecture explained here.

Getting Started

You’ll need to install the following tools:

  • Rust
  • Go
  • protoc
  • just

Or you can use the in-repo nix flake to bootstrap tooling.

Once you have the dependencies installed, you can use the justfile targets locally. Build and run the chain by running both CometBFT and Felidae (the ABCI application), each in its own terminal window. Start CometBFT via:

just cometbft

And the ABCI application via:

just felidae

Finally, to reset the chain state by blowing away both CometBFT and Felidae’s state:

just reset

Note that the application’s genesis file, which contains the initial configuration of the starting state of the chain, is located in ~/.cometbft/config/genesis.json.

Tip: For more verbose logging, run commands with RUST_LOG=info (or RUST_LOG=debug for even more detail).

Testing

Run the standard unit test suite:

just test

Run the integration tests (spawns a 3-validator network per test):

just integration

Block time configuration

Integration tests derive all timing from a configurable block interval (FELIDAE_BLOCK_TIME_SECS, default 1). The default keeps CI fast (~2 min). To test with longer block times (e.g. matching production’s 60s):

just integration 60

Or equivalently:

FELIDAE_BLOCK_TIME_SECS=60 just integration

Setting Up Admin and Oracle

1. Generate Configuration Template

cargo run --bin felidae admin template > config.json

This generates a configuration template (see the Config proto) that you’ll edit to add your own keys as an admin and oracle.

2. Generate Your Admin and Oracle Keypairs

cargo run --bin felidae admin init

This creates your admin keypair. To view your admin public key:

cargo run --bin felidae admin identity

Similarly for oracle:

cargo run --bin felidae oracle init

To view your oracle public key:

cargo run --bin felidae oracle identity

3. Configure config.json

Add your public keys (from step 2) to the authorized lists for both admins and oracles in config.json. For oracles, you’ll need to provide both the identity (public key) and endpoint (domain or IP address) for each oracle.

For a single-validator testing setup, configure the following:

Example chain configuration:

{
  "version": 1,
  "admins": {
    "voting": {
      "total": 1,
      "quorum": 1,
      "timeout": "1day",
      "delay": "0s"
    },
    "authorized": ["YOUR_ADMIN_KEY_HERE"]
  },
  "oracles": {
    "enabled": true,
    "voting": {
      "total": 1,
      "quorum": 1,
      "timeout": "5m",
      "delay": "30s"
    },
    "max_enrolled_subdomains": 5,
    "observation_timeout": "5m",
    "authorized": [
      {
        "identity": "YOUR_ORACLE_KEY_HERE",
        "endpoint": "127.0.0.1"
      }
    ]
  },
  "onion": {
    "enabled": false
  }
}

Note: Each oracle in the authorized array must have:

  • identity: The hex-encoded public key of the oracle (required)
  • endpoint: The endpoint (domain name or IP address) for the oracle (optional, defaults to “127.0.0.1” if omitted)

The endpoint is used by frontends to know where to submit enrollment requests to the oracle set.

Important: You must increment the version number in the config file unless you add the config to the genesis file.

Note: You can now skip steps 3-4 by adding the initial chain config in the genesis file by adding an app_state key with the config, e.g.:

{
  "genesis_time": "2025-09-13T23:47:47.144389Z",
  "chain_id": "my-webcat-testchain",
  "initial_height": 0,
  "app_state": {
    "config": {
      "version": 0,
      "admins": {
        "authorized": [...],
        "voting": { ... }
      },
      "oracles": {
        "enabled": true,
        "authorized": [...],
        "voting": { ... },
        "max_enrolled_subdomains": 5,
        "observation_timeout": "5m"
      },
      "onion": {
        "enabled": false
      }
    }
  }
}

4. Submit Configuration to Chain

cargo run --bin felidae admin config config.json --chain <CHAIN_ID>

Replace <CHAIN_ID> with the chain ID from ~/.cometbft/config/genesis.json.

Once the chain accepts this transaction, you’ll be configured as both admin and oracle. Verify the current configuration:

curl http://localhost:8080/config

5. Post an Oracle Observation

You can now submit oracle observations. For example:

cargo run --bin felidae oracle observe --domain element.nym.re. --zone nym.re.

If you omit the –zone, the oracle will automatically infer the zone from the domain using the Mozilla Public Suffix List (PSL).

After the observation reaches quorum and the delay period expires, the observed hash will be visible in the snapshot:

curl http://localhost/snapshot

Run Oracle as HTTP Server

Instead of using the CLI, you can run the oracle as an HTTP server that accepts observation requests via API:

cargo run --bin felidae oracle server \
  --homedir /persistent/keys \
  --node http://localhost:26657 \
  --bind 127.0.0.1:8081

TK: A client side PoW was added that is not documented here.

The server exposes two endpoints:

  • POST /observe - Submit observation requests (JSON: {“domain”: “example.com.”, “zone”: “com.”})
  • GET /health - Health check endpoint

Example request:

curl -X POST http://localhost:8081/observe \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com.", "zone": "com."}'

Browser Extension

CLI

For Infrastructure Operators

This section is for anyone running or operating WEBCAT infrastructure (validators, oracles, enrollment chain).

TK

WEBCAT Validator Operator

Threat Model

The WEBCAT threat model distinguishes between attacks that the system aims to prevent, and those it aims to detect. The goal is to ensure that all targeted attacks are preventable, and that all large-scale attacks are detectable. An attack is deemed successful if it causes end-user compromise in which users loads client-side assets (such as HTML, JavaScript, WebAssembly, or CSS) that was not authored or intended by the application developers. WEBCAT assumes a powerful adversary whose capabilities may extend to include control over infrastructure and over signing identities of application developers. An attacker may compromise a server or take over one or more domains, depending on jurisdiction and technical capabilities. Services, companies, and individual servers are more at risk from attacks, even by small threat actors, than core infrastructure. Known examples include the jabber.ru MITM attack and the MyEtherWallet BGP hijacking, and likely many more cases that went unnoticed, despite being potentially detectable. The distinction between preventable and detectable attacks is a tradeoff between a heuristic estimate of the probability of real-world attacks and the complexity of infrastructure and design.

Preventable

The system is designed to prevent end-user compromise even if an attacker gains control over:

  • Web server: Full control over the application server, including domain hijacking, BGP or MITM attacks, rogue TLS certificate issuance, or theft of TLS private keys (for a limited amount of time, < cooldown)
  • WEBCAT infrastructure: Up to 1/3 of the WEBCAT enrollment system*’s nodes. Full control over the enrollment frontend, full control over the extension’s CDN list update endpoint.
  • Sigsum log: Full control of the transparency log.
  • Sigsum witnesses: Up to threshold − 1 Sigsum witnesses.

Note: While Sigsum enrollment support threshold signing, Sigstore ones do not. Thus, a compromise of the Sisgstore identity provider, the Sigstore identity, or the CI infrastructure if in use does not

Detectable

Detectability implies the existence of immutable, cryptographically verifiable evidence that an event has occurred, enabling third-party aduting and monitoring. We refer to auditing as the act of checking that a transparency log is behaving properly, and monitoring as checking in real-time or posthumously the information being appended to the log. The system guarantees detectability in the following cases of compromise:

  • Targeted web application updates: due to the transparency logging requirements, a single user cannot be targeted without signing and logging a release. It is up to monitors to check that source code and reproducibility is available for all versions of a web application.
  • Extended web server compromise: if a domain or a webserver are taken over for longer than the cooldown period, then a malicious enrollment change can be successfully committed. However, cryptographic evidence will be preserved and available in the WEBCAT enrollment system.
  • Sigstore Certificate infrastructure: Unauthorized issuance by Fulcio still require transparency logging.
  • Sigstore OIDC provider: Equivalent to the Sigstore Certificate infrastructure case.
  • Sigsum identities: if more than threshold Sigsum identities are compromised according to the enrollment information, then a malicious application update can be shupped. However, non-repudiable information about the event will remain in the chosen Sigsum transparency log.

Combined

TODO: in some cases there’s guarantees even when multiple components misbehave. We cannot cover all cases, but could be nice to highlight a few.

Out-of-scope

The following attacks are explicitly out of scope:

  • WEBCAT supply chain: Supply chain attacks or backdoors in the WEBCAT repositories. While we strive to apply proper supply chain security practices, such as dependency scanning, the system itself is not resisten to this type of threats. We are also limited by the underlying distribution platform, the Mozilla Addons platform (AMO), which currently does not support supply chain integrity validation or transparency logging.
  • Application-level issues: Vulnerabilities or malicious behavior in web applications.

Source Code

WEBCAT aims to be fully transparent and reproducibile. As such, all its components are publicly developed and available under open source licenses.

Repositories

WEBCAT components are distributed in several different repositories, under the freedofpress Github organization.

Demo

The demo websites are also open source:

Research

References

WEBCAT is an ongoing effort and research project. This is a non-exhaustive list of additional references and material:

Frequently Asked Questions

General

How does WEBCAT work?

Sites opt into WEBCAT by publishing a signed manifest of their web application resources. Users with the WEBCAT browser extension verify that loaded resources match the verified manifest, blocking page load if there are any modifications.

How is this different from HTTPS?

HTTPS doesn’t protect your users if the site hosting the web application itself gets hacked.

How is this different from Subresource Integrity (SRI)?

SRI protects against compromised third-party resource hosts (like CDNs) by verifying against specified hashes. However, if the first-party site is hacked, an attacker can modify the code to remove or change the integrity hashes, bypassing SRI protection.

How is this different from Content Security Policy (CSP)?

CSP restricts what resources a document is allowed to load and is primarily designed to protect against attacks like cross-site scripting (XSS). CSP can use hashes in fetch directives to verify script and style integrity, but if the first-party site is compromised, an attacker can modify the CSP headers or meta tags to remove or change those hashes, allowing malicious resources. WEBCAT verifies that resources match their signed manifests, preventing attackers from modifying the policy even if they compromise the site.

What happens if a site gets compromised after enrollment?

If the resources served are modified by the attacker, then users that are using the WEBCAT browser extension would be protected. When those resources are loaded and checked against the WEBCAT manifest, the page load would be halted.

How do users verify that a site is enrolled in WEBCAT?

Users can check if a site is designed to work with WEBCAT via:

https://<domain>/.well-known/webcat/enrollment.json

Users can check if a site has been enrolled using the list provided at:

https://webcat.freedom.press/list.json

Does WEBCAT require browser extensions or special software?

Yes, currently users must use the WEBCAT Browser Extension, available in the Mozilla Add-Ons store.

What browsers are supported?

Currently, just Mozilla Firefox. We’re exploring integration into Tor Browser, and other browser support. One limitiation is that the current WEBCAT architecture requires the Manifest V2 API, which was deprecated by Chromium-based browsers.

How does WEBCAT affect page load performance?

TODO provide some numbers here

For Site Owners

How do I enroll my site in WEBCAT?

You can use the enrollment frontend.

Is there a cost to enroll my site?

It’s free.

Can I unenroll my site?

Yes, you can unenroll your site by removing your enrollment bundle from:

https://<domain>/.well-known/webcat/enrollment.json

and resubmitting your site.

What happens if I need to update my site’s enrollment information?

Simply update your enrollment bundle, and resubmit your site.

Note that changes take 1 day to be updated.

Does WEBCAT work with subdomains?

Yes, but to limit spam, we allow only 5 subdomains per site.

How long does enrollment take?

On the alpha testnet, enrollment takes 1 day to take effect.

Security & Privacy

Does WEBCAT collect user data?

We only store submitted domains.

What if the enrollment infrastructure itself is compromised?

If the enrollment infrastructure itself were compromised, an attacker could unenroll your site from WEBCAT, enabling them to serve malicious code to your users.

Enrollment Infrastructure

Your enrollment infrastructure uses a blockchain. Aren’t they bad for the environment / slow / scammy?

Blockchain technology has unfortunately been associated with scams and speculation, but WEBCAT uses blockchain for a specific technical purpose: providing a decentralized, tamper-resistant registry of site enrollments. There is no financial aspect to this blockchain, we’re using it as a permissioned distributed database that no single party controls.

The blockchain serves as a public ledger where site enrollment records are stored immutably. This ensures that once a site is enrolled in WEBCAT, that enrollment cannot be retroactively modified or deleted by the chain operator, providing the trust guarantees that WEBCAT requires.

For the design of WEBCAT, we wanted to design an infrastructure that has no single point of failure or control, thus ensuring that no single party can prevent enrollments.

We’ve chosen a consensus solution (CometBFT) that minimizes environmental impact and cost. The enrollment infrastructure operates at a much lower transaction volume than typical financial blockchains, and we’re committed to using energy-efficient consensus mechanisms.

Why didn’t you use my favorite blockchain?

The financial aspect of existing blockchains represents an issue for us. Asking users to submit a transaction on a traditional blockchain would mean they need to acquire the native token to pay fees on that chain. That may represent a challenging UX burden or be impossible for users who want to maintain their privacy and anonymity. This latter concern is critical for us since we are planning to enable Tor onion service operators to enroll their sites.