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.

Deferred decisions

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