# 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.