119 lines
5.2 KiB
Markdown
119 lines
5.2 KiB
Markdown
# 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.
|