Skip to content

Threat model

This is the current security model for Witness, not a formal security audit. Witness is pre-1.0, unaudited, and not Byzantine-fault-tolerant. Its guarantees come from the configured threshold, witness keys, client verification, and operational controls.

Security goals

Witness aims to provide:

  • threshold-signed evidence that a SHA-256 hash existed at or before a stated time;
  • content privacy by accepting hashes instead of user content;
  • public verification of attestations against a network configuration;
  • secret-free distribution of public verification configuration;
  • append-only log proofs for light clients and auditors;
  • optional cross-network federation and external anchoring for independent durability; and
  • anonymous abuse control through optional Freebird on public gateways.

Non-goals

Witness does not currently provide:

  • proof of content authorship or ownership;
  • global ordering across independent Witness networks;
  • Byzantine consensus or finality beyond configured threshold signatures;
  • content confidentiality if clients upload content elsewhere or include identifying metadata;
  • anonymity against an operator that correlates IP addresses, timing, User-Agent strings, application identifiers, or reverse-proxy logs;
  • protection from timestamp spam unless Freebird or equivalent admission control is required; or
  • tamper-evident operator logs outside the signed tree-head/proof model.

Assets

Important assets include:

  • witness node private signing keys;
  • witness signing bearer tokens;
  • gateway SQLite databases;
  • gateway network configuration files;
  • federation inbound and outbound auth tokens;
  • external anchor provider credentials and private keys;
  • Freebird verifier configuration and trusted issuer policy;
  • admin API keys, metrics tokens, and WebSocket tokens;
  • release artifacts and container image provenance; and
  • published SDK contents and dependency metadata.

Actors

Actor Capability
Honest client Submits a hash and verifies the returned attestation.
Spam client Attempts to create many attestations cheaply.
Malicious gateway Attempts to omit data, equivocate, or expose metadata.
Compromised witness Signs invalid or misleading attestations.
Threshold collusion Controls enough witnesses to satisfy the network threshold.
Federation peer Cross-anchors batches or submits malformed anchor requests.
External anchor provider Accepts or rejects batch roots and may be unavailable.
Network attacker Observes or modifies traffic when TLS/proxy policy is wrong.
Admin attacker Obtains an admin key/session, database access, or deployment config.

Assumptions and trust decisions

  • Clients verify returned attestations against the correct network configuration.
  • GET /v1/network is a source for a secret-free NetworkVerificationConfig; /v1/config is informational and is not a trust anchor. Clients pin or independently review verification configs when stronger trust is required.
  • Witness signing keys are generated with a secure RNG and stored on protected hosts.
  • BLS membership keys are admitted through a trusted registration process that authenticates each witness/key binding and requires proof-of-possession; current aggregate verification does not perform PoP checks.
  • Witness bearer tokens are high entropy and are not reused across unrelated deployments.
  • Production traffic uses HTTPS at the edge.
  • Reverse proxies forward client IP headers only when the gateway is configured with WITNESS_BEHIND_PROXY=true.
  • Public gateways require Freebird or equivalent admission control.
  • Operators back up gateway databases and configuration before upgrades.

Threats and mitigations

Key and credential compromise

Loss of a witness private key or signing bearer token can let an attacker impersonate a witness or influence attestations. Admin, metrics, WebSocket, federation, and external-provider credentials expose additional control or metadata. Keep secrets out of source control and logs, restrict filesystem and network access, use distinct high-entropy values, and review configuration changes. Thresholds reduce dependence on one witness but do not protect against compromise or collusion of enough witnesses.

Compromised witnesses and threshold collusion

A compromised witness can sign invalid or misleading attestations. A colluding set that controls enough configured witnesses can satisfy the threshold and produce evidence that clients may accept. The threshold is an operator-chosen trust assumption, not Byzantine agreement; use independent operators and client-side verification where that distinction matters. For BLS, the same interpretation additionally depends on trusted key registration and PoP. Without that assumption, distinct IDs in an aggregate do not by themselves establish participation by distinct witnesses.

Gateway omission, equivocation, and database compromise

A gateway may omit records, expose metadata, or present inconsistent views. Gateway SQLite state is persistent operational data, not automatically a tamper-evident log. Clients should verify attestations and proof bundles; auditors should independently verify signed tree-head and consistency-proof chains. Federation and external anchors can add independent durability, but they do not create BFT consensus or protect against enough colluding witnesses/operators.

Admin compromise

An attacker with an admin key/session, database access, or deployment configuration may alter operations, expose metadata, or access credentials. Admin API authentication must be paired with reverse-proxy or network-policy restriction, and database/configuration access must be limited to the service and trusted operators.

Spam, replay, and resource exhaustion

A spam client can submit hashes cheaply or replay admission credentials. The gateway's per-IP limits are defense in depth. Optional Freebird provides the current anonymous admission/rate-limiting boundary: consuming mode calls /v1/verify, records the token nullifier, and rejects reuse; non-consuming mode calls /v1/check and does not prevent reuse. Non-consuming mode therefore requires another replay or rate-control boundary.

Network interception and proxy confusion

Without TLS, a network attacker can observe or modify traffic, including hashes and bearer credentials. A misconfigured proxy can also make forwarded client IPs spoofable. Terminate TLS at a trusted edge, keep internal paths trusted, and enable WITNESS_BEHIND_PROXY only when the proxy is authoritative.

SSRF and malicious outbound destinations

External anchors and Freebird make outbound requests. The hardened client and resolver cover witness, federation, Freebird, and Internet Archive paths, but Trillian and DNS currently use unrestricted reqwest; Ethereum validates its RPC URL before initialization only. A malicious or mistaken provider URL could therefore target internal services. Review provider and verifier URLs as an operational control, and treat the filter as defense in depth rather than a universal guarantee for external anchoring.

Federation and external-anchor abuse

A federation peer may submit malformed anchor requests, and an external anchor provider may accept, reject, or simply fail to process a batch root. Federation and external anchors add independent durability signals but do not establish global ordering, guarantee availability, or provide BFT protection. Validate peer authentication and configurations, review provider credentials and URLs, and treat missing peers or providers as reduced verification or durability.

Availability and durability failure

Witnesses or external providers may be unavailable, and a gateway or disk may fail. Use threshold-aware monitoring, persistent local SQLite storage, tested backups, and deliberate forward-only upgrades. Availability failure does not automatically invalidate previously verified signatures, while a database backup does not prove historical honesty.

Privacy model

Witness receives SHA-256 hashes. Hash privacy depends on the entropy and guessability of the underlying content: a public document or small dictionary value can be guessed by anyone who knows candidate content. Witness does not hide source IP, timing/frequency, User-Agent, application identifiers, or reverse-proxy/load-balancer logs. In addition, without WITNESS_WS_AUTH_TOKEN, /ws/events immediately broadcasts each newly reserved digest and timestamp, exposing submission activity before confirmation. Freebird can make request eligibility unlinkable from issuance, but it does not hide transport metadata by itself. See Privacy properties.

Federation boundary

Federated verification requires valid signatures from configured peer networks, the configured peer threshold, and caller-supplied peer verification configurations. Missing or unavailable peers reduce the achieved verification level. Federation improves independent durability; it is not Byzantine consensus and does not protect against collusion by enough witnesses or operators.

SDK and release controls

The TypeScript SDK uses lossless-json for HTTP responses, request bodies, WebSocket events, and WASM JSON inputs. Generated Rust u64 values use number | bigint; unsafe JavaScript numbers and invalid values are rejected. The explicit AttestationSignatures decoder rejects partial and ambiguous multi-signature/BLS union shapes. Hashes emitted or echoed by the SDK are canonical lowercase hex, but representation is not cryptographic verification. WebSocket authentication challenges without a token stop reconnecting and raise AuthRequiredError.

The npm package is public, pre-1.0, and unaudited. Its release gate covers build, tests, typecheck, generation-drift checks, and npm pack --dry-run; publishing does not imply an audit or BFT tolerance.

Current high-priority gaps

  • external cryptographic and protocol audit;
  • CI gates for formatting, clippy, tests, and release builds;
  • signed release artifacts and image provenance;
  • public API schemas and versioned test vectors;
  • end-to-end tests against current Freebird V4 and V5 verifier flows; and
  • clearer operator guidance for federation token rotation.