# 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: named trust providers

Add trust-store comparison without merging stores or erasing provenance. The
same candidate path should be evaluated independently against providers such as:

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

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

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