browsec/CONCEPT.md

# Browsec: Coarse-Grained Concept

Status: discussion draft  
Date: 2026-08-16

## Purpose

Browsec is a Firefox-derived browser in which trust is not limited to one
central authority. It preserves ordinary cryptographic verification while
making the final trust policy extensible. People may use personal, community,
institutional, or mixed trust models without rebuilding the browser for each
model.

Browsec is an independently governed Firefox downstream. Cooperation with
upstream is welcome where interests coincide, but upstream acceptance is neither
a project requirement nor a security dependency. The trust protocol is first
developed in the browser-neutral JavaScript testbed described in
[ARCHITECTURE.md](ARCHITECTURE.md).

The primary problem is the fragility of one global, authority-maintained Web
PKI. Browsec lets a user supplement or override that global verdict with
narrowly scoped local and community trust providers, without being forced to
trust a local provider globally for every site.

This document defines architectural possibilities and boundaries. It does not
yet select a community algorithm, peer-to-peer protocol, reputation system, or
final user interface.

## Initial plan

### 1. Trust-regulation extensions

Add a privileged, capability-controlled extension class for trust regulation.
Its first hooks are:

- `onSslFailure`: inspect a failed TLS validation and begin an asynchronous
  investigation that may ask the user for a trust decision;
- `onBeforeSslSuccess`: make a fast, blocking decision before Firefox sends HTTP
  data on a connection whose ordinary TLS validation succeeded;
- `onSslSuccess`: asynchronously observe the committed successful decision and
  optionally update local evidence, notify permitted peers, or schedule further
  investigation;
- background activity: maintain local evidence, communicate with explicitly
  permitted services or peers, and implement future community models;
- trust-policy operations: propose additions, removals, distrust rules, and
  temporary exceptions through a browser-owned broker.

Extensions do not receive unrestricted access to Firefox's certificate
database. The browser validates, scopes, records, and applies requested changes.
Hook ordering, time limits, conflict resolution, and failure behavior belong to
the browser core and will be specified later.

`onBeforeSslSuccess` may read prepared local state but must not wait for the
network, peer-to-peer replies, user interaction, or long computation. It returns
within a strict browser-enforced deadline. Its only substantive verdict is
whether the connection is trusted. `Pending` and `abstain` may exist as protocol
states, but are not additional kinds of trust judgment. Timeout and plugin
failure cannot turn rejection into acceptance.

The blocking hook does not directly launch background work. After the browser
commits the connection decision, it publishes `onSslSuccess` with the decision
and relevant immutable TLS facts to authorized background handlers. This event
may update plugin-owned data or enqueue communication without delaying the
connection. Delivery is deduplicated and rate-limited so page subresources and
connection reuse do not create notification storms.

Background disclosure remains capability-controlled. A plugin must not reveal
the user's browsing targets to peers merely because a certificate validated.
Hostnames, addresses, fingerprints, and timing are separate declared disclosure
capabilities, and local policy controls which may leave the browser.

Each privileged security extension has an isolated, durable, general-purpose
data store. It may retain observations and any extension-specific information
needed for future analysis; storage is not limited to formalized trust
decisions. The browser controls capability grants, quotas, inspection, export,
deletion, and network disclosure. An extension cannot access another
extension's store or treat stored material as unattributed browser fact.

The user can also initiate investigation through an unforgeable browser-chrome
control on successful or failed connections. The working action **Record
security concern** captures the current immutable security context and opens
the protected investigation UI. It records that the user requested evidence,
not that the service has already been proven unsafe. Authorized extensions may
analyse and retain the capture while preserving provenance and privacy limits.

Trust plugins control trust only. They do not gain general authority over
navigation, page contents, cookies, credentials, downloads, browser settings,
or arbitrary Firefox internals. Their enforceable output is a scoped **trusted**
or **not trusted** verdict, optionally persisted through the trust-policy broker.
Explanations, evidence, and warnings support that verdict but do not create
additional browser-control powers.

Asynchronous hooks may open a browser-mediated interactive plugin page so the
plugin can explain evidence or ask the user to decide. Such a page runs in a
privileged trust-plugin surface, is visibly attributed to the plugin, and
remains distinct from Browsec's immutable built-in handler. A synchronous hook
cannot wait for this UI. It may instead request that navigation be suspended or
redirected into an asynchronous investigation; after the user decides, the
browser starts a new validation attempt using the resulting scoped trust rule.

#### Ordered plugin chain and decision journal

Every TLS decision passes through an ordered chain containing one or more trust
plugins. The final member is Browsec's built-in diagnostic and decision handler;
it cannot be removed, replaced, reordered, or impersonated by an installed
plugin.

The browser owns an append-only **decision journal** for the connection. It
starts with immutable TLS facts and ordinary Firefox validation results. Each
plugin receives a capability-filtered, read-only view of those facts and earlier
journal entries, and may append an attributed structured entry. A plugin cannot
edit, delete, or obscure another plugin's entry.

Initial entry kinds are deliberately simple:

- **evidence**: a factual observation with provenance;
- **vote**: a recommendation of trusted or not trusted;
- **warning**: a risk that must remain visible even if the connection is
  allowed;
- **resolution**: a trusted or not-trusted verdict and its exact scope;
- **error/abstention**: the plugin could not or chose not to decide.

The user configures each plugin's role rather than treating all entries as equal:

- **observer**: may add evidence and warnings only;
- **advisor**: may also add non-binding votes;
- **decision authority**: may propose a binding resolution within explicitly
  granted scope;
- **veto authority**: may return not trusted within explicitly granted scope.

These roles are browser-enforced capabilities. A plugin cannot promote its own
vote or warning into a decision. A decision authority's result remains subject
to non-overridable browser safety rules and to any higher-precedence local deny
policy.

The built-in final handler consumes the complete journal. When policy yields one
valid result, it applies or confirms that result and records why. When results
are absent, conflicting, timed out, or require consent, it displays the journal
to the user in the privileged diagnostic UI. It presents a readable synthesis
while preserving the attributed original entries for inspection.

"Vote" does not initially imply majority rule. Plugins may represent communities
of very different size and independence, and several plugins may rely on the
same underlying source. The later policy model decides how votes, warnings,
vetoes, and authorities compose; the journal merely preserves their provenance
and order.

The synchronous journal used by `onBeforeSslSuccess` is sealed when its deadline
expires. Later background findings create entries in a related investigation
record and may affect future connections, but cannot rewrite the decision made
for an existing connection.

### 2. The same trust framework for browser extensions

Extend the model from website certificates to browser-extension packages.
Extension identity is based on signed content and publisher-key continuity, not
only approval by one central directory. Communities and participants may issue
signed endorsements, warnings, and revocations.

Community evidence does not by itself grant runtime permissions. Package
authenticity, trust recommendation, installation approval, and capability
authorization remain separate decisions.

### 3. Community security-announcement channel

Provide a channel for signed, critical security announcements to propagate
through communities. Announcements may concern certificates, CAs, domains,
participants, extension packages, publishers, or trust plugins.

An announcement is evidence, not executable control. Its origin, signatures,
time, scope, forwarding path, and expiration must be visible. Local policy
decides whether it informs the user, quarantines an item, or blocks it. No
community message may silently install code or permanently expand trust.

### 4. Signed trust entities

Introduce two initial entities:

- **Participant**: a person, service, or device represented by a cryptographic
  identity and a signed profile;
- **Community**: a signed definition of membership, governance keys, applicable
  scope, and rules for accepting statements or decisions.

Signatures prove which key made a statement; they do not prove that the
statement is true or that the key represents the claimed human. Key rotation,
recovery, delegation, compromise, and community governance are necessary parts
of the later identity design.

### 5. Built-in final diagnostic handler

Ship a basic browser-owned trust handler at the end of the hook chain. If no
earlier policy safely resolves a TLS failure, it shows the certificate
investigation page, explains the broken trust path, displays plugin findings,
and presents the available browser-enforced choices.

This handler provides a dependable fallback even when trust plugins are absent,
disabled, conflicting, timed out, or broken. It cannot be replaced by an
ordinary web page.

### 6. Unmistakable trusted UI

Security decisions appear only in browser-owned privileged UI with a stable,
recognizable treatment that ordinary pages and ordinary extensions cannot draw
or overlay. The browser chrome identifies:

- that the surface belongs to Browsec;
- which trust plugin supplied each finding or recommendation;
- which action will be enforced by the browser;
- the scope and duration of the proposed decision.

Visual distinction is defense in depth, not the sole security boundary. Process
isolation, an unforgeable privileged origin, restricted APIs, trusted event
handling, and protection from page-controlled fullscreen or overlays are also
required.

## Core principles

1. **Facts before policy.** Cryptographic facts are recorded independently from
   community or institutional judgments.
2. **Plural trust.** No single trust model is built in as universally correct.
3. **Local sovereignty.** The final decision follows the user's local policy.
4. **Least authority.** Plugins receive declared capabilities and brokered
   operations, not direct control of the verifier or trust database.
5. **Visible provenance.** Every recommendation, announcement, and decision
   identifies its source and supporting evidence.
6. **No silent widening.** Trust cannot become broader in target, namespace,
   duration, or permission without an explicit applicable policy.
7. **Safe fallback.** Plugin absence or failure leads to the browser-owned
   diagnostic handler, not automatic acceptance.
8. **Revocability and audit.** Decisions can expire or be revoked and leave a
   local, inspectable record.
9. **Code trust is not code permission.** Endorsement may justify considering an
   extension, but cannot grant its capabilities.
10. **Announcements are not commands.** Community communication supplies signed
    evidence; browser policy controls its effects.

## First architectural milestone

Before forking Firefox, define and prototype only the seams:

1. immutable TLS success/failure event records;
2. a versioned trust-plugin hook interface separating fast blocking decisions
   from asynchronous observation and background work;
3. a browser-owned append-only decision journal with attributed plugin entries;
4. a capability and trust-change broker;
5. signed Participant, Community, and Announcement envelopes;
6. a browser-owned hook coordinator and final diagnostic handler;
7. an unforgeable security-decision UI surface.

The prototype may use Firefox Developer Edition or Nightly privileged extension
experiments. A Firefox fork is considered only after these interfaces are small,
testable, and sufficiently stable.

## Deferred decisions

- community membership and governance models;
- peer-to-peer transport and discovery;
- ranking, quorum, reputation, and resistance to fake identities;
- global versus community-specific naming;
- detailed hook ordering and conflict precedence;
- exact temporary-trust semantics;
- extension distribution, reproducible builds, and update consensus;
- the final visual language of the investigation page.

These are intentionally deferred so the first architecture enables experiments
without prematurely declaring one social trust system correct.