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`](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.