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.

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.