browsec/ARCHITECTURE.md

# Browsec Architecture Decisions

Status: active  
Date: 2026-08-16

## ADR-001: Firefox is the first browser integration

Browsec will be an independently governed Firefox downstream. Upstream Firefox
remains a source of browser-engine and security updates, but Mozilla acceptance
is not a project requirement or a trust-policy dependency.

Reasons:

- Firefox supports privileged WebExtension Experiments for rapid API work.
- Its extension background model is suitable for continuously prepared trust
  evidence.
- Existing Firefox certificate-override machinery is useful for early work.
- Firefox ESR provides a plausible downstream maintenance base.
- MPL 2.0 is compatible with an open, independently distributed browser.

The integration must use independent branding, profiles, release signing,
updates, and governance.

## ADR-002: TrustLab precedes deep browser changes

The trust protocol will first be implemented in `trustlab/`, a browserless,
host-neutral JavaScript testbed. It runs under Node.js/V8 during development but
must not expose Node-specific facilities to trust plugins.

TrustLab exists to stabilize:

- immutable TLS fact records;
- the append-only decision journal;
- independent evidence collection;
- ordered trust-decision plugins;
- scoped Boolean trust verdicts;
- the immutable built-in fallback/final handler;
- plugin timeouts, failures, provenance, and audit records;
- synthetic certificate scenarios and conformance tests.

An optional browser-hosted TrustLab UI will later exercise interactive plugin
pages without requiring a Firefox build.

## ADR-003: Trust plugins decide; the browser enforces

A trust plugin's only enforceable policy result is a scoped `trusted` or
`not-trusted` verdict. Plugins may also append evidence and warnings. Operational
states such as timeout, error, abstention, and pending are not trust verdicts.

The browser core is a reference monitor. It verifies plugin identity,
capabilities, scope, journal integrity, deadlines, and binding to the active TLS
connection, then executes the plugin-chain result. It does not introduce a
separate hidden trust policy.

The built-in final handler is permanently last. It preserves an earlier valid
terminal verdict; when no plugin decides, it provides the browser-owned
diagnostic UI and obtains or supplies the final Boolean verdict.

## ADR-004: Trust policy is an overlay

Browsec policy will primarily live in its own versioned, auditable overlay rather
than directly encoding all decisions in Firefox/NSS certificate trust bits. The
overlay must eventually express host and port scope, certificate or key binding,
CA namespace constraints, expiration, explicit distrust, provenance, and
community evidence.

Conventional global CA import may still be offered when global trust is exactly
what the user intends.

## ADR-005: Protocol 0.1 is TLS-only and TypeScript-defined

The first plugin contract addresses substitution and restriction of TLS trust
authorities only. It deliberately excludes general browser automation,
announcements, peer-to-peer transport, timers, and post-navigation hooks. Those
may be layered on later without enlarging the authority of the TLS decision
surface.

The compiler-checked contract exposes three hooks:

- `collectEvidence` contributes attributed facts, warnings, and advisory votes;
- `onBeforeTlsAccept` synchronously accepts or rejects a normally valid TLS
  connection using prepared local state;
- `onTlsFailure` asynchronously investigates a failed validation and may obtain
  a browser-mediated user decision before a fresh connection attempt.

A plugin exports one registration object through `defineTrustPlugin`. Its static
manifest declares supported modes and requested capabilities; separate local
configuration grants its active mode and authority. Every terminal verdict is
Boolean and contains an explicit certificate-or-authority scope, lifetime, and
supporting journal references.

## Required Firefox additions

The exact patch boundaries will be established after TrustLab protocol v0 and a
privileged-extension integration spike. Expected additions are:

1. Produce immutable, serializable TLS validation facts for successful and
   failed verification, including presented and constructed chains.
2. Invoke a bounded `onBeforeTlsAccept` trust pipeline before HTTP data is sent.
3. Route failed validation into asynchronous trust investigation.
4. Publish post-decision `onTlsAccepted` and `onTlsRejected` events.
5. Enforce the Browsec trust-policy overlay in all relevant network paths,
   including HTTP/1.1, HTTP/2, HTTP/3, WebSocket, workers, and connection reuse.
6. Host capability-controlled trust plugins and their background activity.
7. Provide browser-mediated interactive plugin surfaces.
8. Provide an unforgeable built-in security frame and final diagnostic handler.
9. Broker scoped trust changes without granting plugins arbitrary NSS/database
   access.
10. Isolate Browsec branding, profiles, updates, signing keys, and audit data.

## ADR-006: Security extensions have private evidence storage

Privileged security extensions need durable, general-purpose private storage,
not merely access to the formal trust-policy overlay. An extension may retain
observations, indexes, historical certificates, intermediate analysis, remote
responses, user annotations, model state, or other information required by its
declared security function.

The browser brokers storage rather than exposing arbitrary Firefox databases or
the storage of another extension. Each extension receives an isolated namespace
with explicit capability grants, quotas, schema/version ownership, migration,
backup, inspection, export, and deletion controls. Stored information does not
become trusted evidence merely because a privileged extension wrote it; all
later journal contributions still identify their source and provenance.

The built-in Velvet Hammer extension separately owns durable policy and
investigation storage. Trust decisions remain structured and auditable even
when their supporting evidence comes from an extension's general store.

## ADR-007: Users can initiate evidence capture

Browsec must provide an unforgeable browser-chrome action available on both
successful and failed TLS connections. Its working label is **Record security
concern**; final wording requires user research. It must not prematurely assert
that the site is insecure.

Activation freezes a browser-produced observation of the current security
context and opens the protected investigation surface. The record may include
TLS facts, presented and constructed certificates, path analysis, applicable
policy, timestamps, and user-supplied notes. It excludes page contents,
credentials, cookies, authorization headers, private keys, and TLS session
secrets unless a future, separately consented forensic capability explicitly
defines otherwise.

Authorized security extensions may receive the immutable capture event and add
attributed evidence or store extension-private analysis. They cannot rewrite
the browser observation or silently transmit it without a separately granted
network capability and applicable user consent.

## Deferred decisions

- Firefox source revision and ESR release;
- plugin package format and signing envelope;
- persistent policy and extension-private storage technology;
- P2P transport and community governance;
- release governance and threshold signing;
- precise UI design and accessibility treatment.