Security overview

Witness is pre-1.0 and has not received an external security audit. It is not Byzantine-fault-tolerant. Operators must review the code, configuration, and deployment against their own threat model before relying on it.

Witness separates these boundaries:

• witness nodes hold private signing keys and sign only for their configured network;
• gateways admit requests, collect threshold signatures, persist records, expose proofs, and coordinate batching, federation, and optional anchors;
• auditors independently walk signed tree-head and consistency-proof chains;
• clients verify threshold signatures and proof bundles against a reviewed network verification configuration.

Witness timestamps SHA-256 hashes, not user content. Hashing is not a promise of anonymity or confidentiality when content is guessable or when clients leak content and identifiers elsewhere.

Security controls and boundaries

• Witness signing endpoints use bearer authentication and should be reachable only from trusted gateways or private networks.
• Admin routes require an API key when enabled, and should also be restricted by a reverse proxy, VPN, or network policy.
• Metrics are public unless WITNESS_METRICS_TOKEN is set or the route is blocked. WebSocket events are public unless WITNESS_WS_AUTH_TOKEN is set; the default stream immediately broadcasts each newly reserved digest and timestamp, before confirmation.
• Federation inbound routes should use federation.inbound_auth_token before internet exposure.
• Production traffic must use HTTPS at the edge. The gateway itself speaks plain HTTP; trusted proxy handling is required before enabling WITNESS_BEHIND_PROXY.
• The built-in SSRF filter must remain enabled for Freebird, witness, federation, and Internet Archive requests. Trillian and DNS anchor requests currently use unrestricted reqwest, while Ethereum has URL preflight validation only; do not treat all external anchoring traffic as SSRF-safe.
• Built-in per-IP limits are defense in depth. Public gateways need Freebird or equivalent admission control when timestamp abuse is in scope.

Read next

• Threat model — goals, assets, actors, threats, assumptions, and non-goals.
• Privacy properties — hash privacy and observable metadata.
• Non-goals — claims Witness explicitly does not make.
• Cryptographic assumptions — signature, threshold, hash, and proof assumptions.
• Audit status — unaudited status and known gaps.
• Operational risks — deployment failure and trust boundaries.
• Freebird — the optional current anonymous rate-limiting integration and its replay/privacy tradeoffs.

For vulnerability reporting and version policy, see the repository's SECURITY.md. For production procedures, see the operator documentation.