browsec/ROADMAP.md

Browsec wake-up point

This document records the project's working state at the end of its first development session. It is a compact handoff for the next session, not a replacement for the concept, architecture, or detailed design documents.

What works now

• Velvet Hammer executes a rigid, typed TLS trust-plugin chain with separately granted observer, advisor, decision-authority, and veto-authority modes.
• Plugins receive immutable TLS facts and contribute to an append-only, attributed decision journal.
• Terminal decisions are Boolean, explicitly scoped, time-bounded, and name exactly which TLS errors they override.
• Certificate rules and exact-DER authority rules are implemented by a local policy overlay that itself participates as an ordinary trust plugin.
• Authority rules cannot override hostname, validity, signature, or unrelated TLS failures.
• TrustLab can probe real TLS servers without modifying browser or operating system trust.
• The dependency-free DER explorer preserves original certificates, decodes security-relevant extensions, and synchronizes ASN.1 structure with exact hexadecimal byte ranges.
• Live CA eligibility is derived from signed Basic Constraints, Key Usage, and critical-extension semantics rather than adapter assertions.
• The explainable path builder tests possible issuer edges, enumerates acyclic paths, distinguishes structural completion from validation, and attributes trust termini to named providers.
• Versioned investigation bundles export original DER, normalized evidence, path analysis, journal, verdict, and policy history for offline reproduction. Import reparses DER and verifies fingerprints and derived authority facts.

Invariants we keep

1. Raw evidence is immutable and remains distinct from interpretation.
2. Every claim, vote, warning, verdict, rule, and trust anchor has an attributed source.
3. Trust is Boolean at the final boundary; uncertainty remains visible in the journal rather than leaking into an ambiguous terminal value.
4. Plugins receive only explicitly granted authority and cannot silently widen host, port, certificate, namespace, lifetime, or overridden-error scope.
5. The built-in final handler is always present and cannot be replaced.
6. Trusting a CA repairs trust-anchor failure only; it never forgives an invalid leaf or an independent path failure.
7. Unsupported critical semantics fail closed.
8. Imported decisions are evidence and are never silently installed as active local policy.
9. A result is never merely “trusted”; it is trusted by a named provider under a specific policy snapshot.

The hammer permits no silent widening of scope.

Known limitations

• Node/OpenSSL does not reliably expose the boundary between certificates sent by the server and certificates added during path construction. TrustLab labels this limitation explicitly.
• Candidate path construction currently operates on certificates already observed by the probe; it does not fetch missing intermediates through AIA.
• Several extensions are preserved but not yet semantically decoded, including Name Constraints, Certificate Policies, AIA, CRL Distribution Points, Policy Constraints, and TLS Feature.
• The path builder does not yet evaluate Name Constraints, policy trees, revocation, Certificate Transparency, or algorithm-policy requirements.
• The local policy overlay is in-memory; durable storage and migration rules have not yet been designed.
• 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: Firefox host and privileged security extensions

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.

The first reconnaissance baseline and proposed patch sequence are recorded in FIREFOX_INTEGRATION.md. It pins the inspected Firefox commit and must be updated whenever that baseline changes.

The next milestone should establish the smallest real Firefox integration:

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

• Decode and enforce Name Constraints and the remaining path-relevant X.509 extensions.
• Add permissioned AIA retrieval while preserving the distinction between server-presented, locally stored, and downloaded certificates.
• Compare investigation bundles across time for key, issuer, SAN, extension, policy, and path changes.
• 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 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.