Operator documentation

Witness is pre-1.0, unaudited software. A deployment is experimental until the operator has reviewed the code, configuration, and operational controls against its own threat model. Witness is not Byzantine-fault-tolerant (BFT). Threshold signatures provide the guarantees of the configured witness set and threshold; they do not make the operators or witnesses mutually trustworthy.

This section is for operators of gateways and witness nodes:

• Run a witness — operate one signing node.
• Run a gateway — operate the public API and aggregator.
• Federation setup — configure optional cross-anchoring.
• Key management — protect signing keys and bearer credentials.
• Monitoring — health, metrics, logs, and incidents.
• Backups — SQLite persistence and restore preparation.
• Upgrades — reviewed, forward-only upgrades.
• Abuse and rate limiting — IP controls and optional Freebird admission.
• Jurisdictional diversity — an operational consideration, not a protocol guarantee.

Security decisions and limitations are documented separately in the security overview, threat model, and privacy properties.

Deployment boundary

The gateway speaks plain HTTP and does not terminate TLS itself. Put it behind a correctly configured TLS-terminating reverse proxy or load balancer for production traffic. Witness signing endpoints should be reachable only from trusted gateways or private networks and must use high-entropy bearer tokens.

Keep network.json, private signing keys, bearer tokens, API keys, database files, and backups access-controlled. Do not put secrets in source control, public images, logs, or examples.

Unless WITNESS_WS_AUTH_TOKEN is configured or the route is blocked upstream, /ws/events is unauthenticated and immediately broadcasts each newly reserved digest and reservation timestamp. Restrict it when hash or submission-timing exposure is not acceptable.