79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
# TrustLab
|
|
|
|
TrustLab is the browser-neutral executable model of Browsec's trust-plugin
|
|
protocol. It currently runs under Node.js without external dependencies, but
|
|
plugins receive only portable JavaScript values and TrustLab capabilities.
|
|
|
|
The initial runner separates two phases:
|
|
|
|
1. Evidence plugins independently inspect the same immutable TLS facts. Their
|
|
attributed results are appended deterministically to the journal.
|
|
2. Decision plugins inspect the sealed evidence view in configured order. The
|
|
first authorized Boolean verdict is terminal. Browsec's immutable built-in
|
|
handler finalizes that result or supplies the safe fallback.
|
|
|
|
Run:
|
|
|
|
```sh
|
|
npm test
|
|
npm run check
|
|
npm run build
|
|
npm run demo
|
|
npm run ui
|
|
```
|
|
|
|
`npm run ui` serves the browser-hosted testbed at `http://127.0.0.1:4173`.
|
|
The page uses synthetic TLS records and the same portable TrustLab runner used
|
|
by the tests. It does not make real TLS decisions.
|
|
|
|
## Current protocol boundary
|
|
|
|
Plugins may return evidence, warnings, and a scoped Boolean trust verdict. They
|
|
cannot access Node.js facilities through the protocol, mutate TLS facts or
|
|
journal entries, or perform browser actions.
|
|
|
|
This first slice intentionally omits persistence, package signatures, community
|
|
identities, networking, and real X.509 parsing. The included interactive UI is a
|
|
security-surface prototype, not browser integration.
|
|
|
|
## TLS-only plugin API
|
|
|
|
The strict TypeScript contract is defined in [`sdk/plugin-api.ts`](sdk/plugin-api.ts).
|
|
A plugin exports one object created with `defineTrustPlugin`; local configuration
|
|
separately grants its active mode and scope.
|
|
|
|
The initial API intentionally exposes only:
|
|
|
|
- `collectEvidence` for attributed evidence, warnings, and advisory votes;
|
|
- `onBeforeTlsAccept` for a fast synchronous decision after normal validation;
|
|
- `onTlsFailure` for asynchronous investigation of a failed validation.
|
|
|
|
Every terminal result is Boolean and must include a discriminated certificate or
|
|
authority scope, an explicit lifetime, and the journal entries supporting it.
|
|
See [`examples/strict-plugin.ts`](examples/strict-plugin.ts) for a compiler-checked
|
|
registration example.
|
|
|
|
## Probe a real server
|
|
|
|
The read-only probe turns a live TLS connection into the same immutable facts
|
|
used by the simulator:
|
|
|
|
```sh
|
|
npm run probe -- example.com
|
|
npm run probe -- broken.example:8443 --json
|
|
```
|
|
|
|
It records DER and SPKI SHA-256 fingerprints and independently checks hostname,
|
|
validity periods, and adjacent certificate signatures. It never installs trust
|
|
or changes the operating system. The report labels its current chain-source
|
|
limitation rather than claiming that OpenSSL's peer chain is exactly what the
|
|
server transmitted.
|
|
|
|
Authority scopes identify the exact DER-encoded CA certificate with
|
|
`authorityCertificateSha256`. TrustLab verifies that it appears in the active
|
|
chain, has CA Basic Constraints in the supplied facts, and permits
|
|
`keyCertSign`. The in-memory policy overlay applies that authority only to the
|
|
declared host namespace and participates in retries as an ordinary trust plugin.
|
|
An authority rule may override trust-anchor failures only; it cannot excuse an
|
|
expired certificate, a hostname mismatch, or another independent TLS failure.
|