From 55f614f6fc5c2b0e22354299edeb77f89dde4767 Mon Sep 17 00:00:00 2001 From: sergeych Date: Mon, 17 Aug 2026 16:46:38 +0400 Subject: [PATCH] Restore security extension platform as primary goal --- ARCHITECTURE.md | 41 ++++++++++++++++++++++++++++++++++- CONCEPT.md | 14 ++++++++++++ DESIGN.md | 30 ++++++++++++++++++++++++++ ROADMAP.md | 56 +++++++++++++++++++++++------------------------- SESSION_NOTES.md | 46 +++++++++++++++++---------------------- 5 files changed, 131 insertions(+), 56 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 64071c2..af2635a 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -108,11 +108,50 @@ privileged-extension integration spike. Expected additions are: 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 database technology; +- persistent policy and extension-private storage technology; - P2P transport and community governance; - release governance and threshold signing; - precise UI design and accessibility treatment. diff --git a/CONCEPT.md b/CONCEPT.md index 4951ff9..d81007a 100644 --- a/CONCEPT.md +++ b/CONCEPT.md @@ -69,6 +69,20 @@ 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** diff --git a/DESIGN.md b/DESIGN.md index 072368d..a352c44 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -38,6 +38,10 @@ trust policy. weaken them. 7. Keep all decisions inspectable, revocable, exportable, and attributable. 8. Isolate research browsing from the user's everyday browser data. +9. Let the user begin an investigation on any connection, including one that + conventional TLS validation accepted. +10. Let privileged security extensions retain arbitrary extension-specific + evidence and analysis in isolated, user-governed storage. ## 3. Non-goals @@ -135,6 +139,32 @@ Every decision has a visible expiration, can be revoked immediately, and is written to a local audit log. The investigation report stores fingerprints and metadata, never private keys or page contents. +### 6.5 A valid certificate does not end investigation + +The absence of a TLS warning does not prove that a service is benign or that +its certificate was expected. Browsec therefore exposes a browser-owned +**Record security concern** action on successful and failed connections. The +action captures facts rather than asserting a conclusion, then opens the same +protected investigation surface used for automatic TLS failures. + +The initial capture includes the requested origin, observation time, TLS +parameters, original certificates, validation and path results, applicable +local policy, and optional user notes. It excludes browsing content and secrets. +Extensions may append attributed findings according to their capabilities. + +### 6.6 Evidence storage is broader than policy storage + +The formal trust-policy database stores narrow enforceable decisions. It is not +a sufficient data model for security extensions. Each privileged security +extension also receives isolated general-purpose storage for information it +chooses to collect for later security analysis. + +The browser must provide quotas, storage-use visibility, export, deletion, +migration, and per-extension network controls. One extension cannot read +another extension's store. Writing data does not grant it evidentiary authority: +when stored information later enters an investigation journal, its extension +source and derivation remain visible. + ## 7. Investigation page ### 7.1 Page structure diff --git a/ROADMAP.md b/ROADMAP.md index f9c5021..315d839 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -68,30 +68,27 @@ replacement for the concept, architecture, or detailed design documents. - This is still a browser-neutral research tool. It reports what Browsec would decide but does not yet control a Firefox network connection. -## Next milestone: named trust providers +## Next milestone: Firefox host and privileged security extensions -Add trust-store comparison without merging stores or erasing provenance. The -same candidate path should be evaluated independently against providers such as: +The primary product is a Firefox downstream that hosts full-fledged security +extensions. TrustLab and Velvet Hammer are the proven reference implementation, +not the final delivery environment. -- Mozilla's root program snapshot; -- the operating-system trust store; -- an explicitly imported PEM/DER anchor collection; -- the user's local allow and distrust policy; -- configured community trust providers. +The next milestone should establish the smallest real Firefox integration: -The first implementation should provide: - -1. A small trust-provider interface returning exact anchor fingerprints, - provider identity, snapshot identity, observation time, and Boolean - recognition or distrust. -2. Safe import of PEM and DER anchor collections with duplicate detection and - DER-derived metadata. -3. Independent results per provider. No implicit union of trust stores. -4. UI comparison showing why the same path terminates differently under each - provider. -5. Investigation-bundle preservation of provider and snapshot provenance. -6. Tests proving that a provider's trust cannot become anonymous global trust - or escape its configured scope. +1. Map NSS/PSM validation and certificate data into immutable `TlsFacts`. +2. Define the privileged security-extension package, identity, capability, and + local grant model. +3. Invoke the bounded success/failure trust hooks and enforce a fresh scoped + retry without granting arbitrary NSS database access. +4. Host the irremovable Velvet Hammer root extension in unforgeable browser UI. +5. Provide isolated general-purpose durable storage to each privileged security + extension, including quota, migration, inspection, export, and deletion. +6. Implement durable, auditable Velvet Hammer policy and investigation storage. +7. Add a browser-chrome **Record security concern** action for user-initiated + evidence capture on successful as well as failed connections. +8. Prove one end-to-end navigation through a deliberately broken certificate, + user decision, stored scoped rule, and fresh connection retry. ## Later milestones @@ -101,14 +98,15 @@ The first implementation should provide: server-presented, locally stored, and downloaded certificates. - Compare investigation bundles across time for key, issuer, SAN, extension, policy, and path changes. -- Add several trust-store adapters and historical snapshot comparison. -- Design durable, auditable local policy storage. -- Map the proven TrustLab contracts onto Firefox NSS/PSM integration points. +- Add named trust providers, trust-store adapters, and historical snapshot + comparison as optional security extensions. +- Develop distributed/community trust as a later extension family rather than + a prerequisite for the browser platform. ## Resume here -Begin by defining the trust-provider TypeScript contract and two browserless -reference providers: an explicit in-memory anchor set and a local distrust set. -Feed their separately attributed results into the existing path analysis and -display the comparison without changing the current final-decision semantics. - +Begin by documenting the Firefox/NSS/PSM integration seam and selecting a +specific Firefox revision for a privileged-extension spike. In parallel, define +the extension-private storage broker and the browser-produced manual evidence +capture record. Do not begin distributed-trust implementation before this host +platform works. diff --git a/SESSION_NOTES.md b/SESSION_NOTES.md index d874019..b75e8f6 100644 --- a/SESSION_NOTES.md +++ b/SESSION_NOTES.md @@ -228,35 +228,30 @@ There were **38 passing tests**. Live checks also behaved as intended: Use `git status --short` before new work. Existing uncommitted changes, if any, must be treated as belonging to the user. -## Exact next implementation seam +## Corrected next implementation seam -Implement named trust providers before adding more global policy behavior. +The primary goal is the Browsec Firefox host and its privileged security- +extension platform. Distributed trust and named trust providers are later +extensions that may be implemented by us or the community; they must not delay +the browser integration. -Start with a strict TypeScript contract that accepts a candidate path and -immutable certificate facts, then returns an attributed Boolean recognition or -distrust result containing: +Begin with three connected designs: -- provider ID and human name; -- provider kind; -- snapshot ID/version; -- observation or effective time; -- exact recognized/distrusted anchor fingerprint; -- supporting reason codes. +1. The narrow Firefox NSS/PSM adapter that creates `TlsFacts`, invokes the trust + chain, and performs a fresh scoped retry. +2. The privileged-extension host, package/capability grants, protected UI, and + isolated general-purpose storage broker. Extensions may retain any + information needed for their security function, subject to explicit + capabilities, quotas, inspection, export, deletion, and network controls. +3. A browser-owned **Record security concern** action that lets the user capture + immutable evidence and open Velvet Hammer even when conventional TLS + validation succeeded. User-generated concern is an observation trigger, not + a pre-written verdict that the service is unsafe. -Build two browserless reference providers first: - -1. An explicit in-memory anchor set. -2. An explicit local distrust set. - -Evaluate them independently against each candidate path. Do not union provider -stores, do not collapse conflicting results, and do not change final-decision -semantics yet. Show a comparison matrix in TrustLab and preserve provider -snapshots in investigation bundles. - -After that, add safe PEM/DER anchor collection import with duplicate detection. -Only later add real Mozilla/OS adapters, AIA issuer retrieval, Name Constraints, -revocation, Certificate Transparency, historical comparisons, durable policy, -and Firefox NSS/PSM integration. +Then connect the already implemented Velvet Hammer reference extension to this +host, add durable policy/investigation storage, and prove an end-to-end failed +navigation and retry. Only after the platform works should work resume on named +or distributed trust providers. ## Files to open first next session @@ -270,4 +265,3 @@ and Firefox NSS/PSM integration. The conceptual documents remain authoritative for broader intent: [`CONCEPT.md`](CONCEPT.md), [`ARCHITECTURE.md`](ARCHITECTURE.md), and [`DESIGN.md`](DESIGN.md). -