113 lines
5.7 KiB
Markdown
113 lines
5.7 KiB
Markdown
# 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 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.
|