Skip to content

System overview

Witness separates coordination, signing, shared verification, and client consumption. The separation is a code-organization and trust-boundary choice; it is not a promise that any one component is independently secure.

Layers

+----------------------+       +-------------------------+
| Client / SDK / CLI   |       | witness-auditor         |
| submit and verify    |       | independent STH walker  |
+----------+-----------+       +------------+------------+
           | HTTP                         | HTTP
           v                              v
+--------------------------------------------------------+
| witness-gateway                                        |
| admission | durable jobs | aggregation | SQLite       |
| batches   | STHs        | federation  | anchors      |
+-------------------+--------------------+---------------+
                    |                    |
                    | /v1/sign           | peer / provider HTTP
                    v                    v
          +----------------+   +-------------------------+
          | witness-node   |   | peer gateways / anchors |
          | private key    |   | optional durability     |
          +----------------+   +-------------------------+

          witness-core is the shared library used by all
          Rust verification and signing call paths.

Workspace responsibilities

witness-core

This is a pure library with no private-key custody, HTTP server, or outbound network operation. It defines Attestation, SignedAttestation, network configuration projections, Merkle and log proof types, cross-anchor types, and external-anchor proof types. It implements the Ed25519 and BLS12-381 operations and the corresponding verification paths.

The canonical attestation signing message is the hash, timestamp, a length-prefixed network ID, and sequence number. Changes to this serialization would affect signatures and verification.

witness-gateway

This is the main binary. It accepts hash submissions, deduplicates and reserves jobs, contacts witness nodes, verifies individual and final results, persists confirmed attestations, closes batches, issues Signed Tree Heads, and starts optional federation and external-anchor work.

witness-node

Each node is a separate HTTP service and holds one private key. It signs an attestation only after bearer authentication and basic network and clock checks. It returns a signature share tagged with its witness ID.

Client-side components

witness-cli and witness-client are gateway clients. They do not contact witness nodes for ordinary operation and do not sign. Their verification functions execute locally against a caller-supplied public verification configuration. witness-core-wasm exposes selected verification operations to WASM consumers without exposing key generation.

witness-auditor is also a client. It retains accepted STHs and anomalies in its own SQLite database so a gateway rollback can be noticed across auditor restarts.

Trust and data boundaries

 private operational data                  public verification data
 +----------------------------+            +----------------------------+
 | witness private key        |            | witness IDs + public keys  |
 | witness/gateway bearer    |  project   | threshold + scheme         |
 | federation credentials    |----------->| federation verification    |
 | external provider secrets |            | rules                       |
 +----------------------------+            +----------------------------+
          node / gateway                             client / auditor

The gateway's GET /v1/network surface is intended to provide a secret-free verification configuration. GET /v1/config is informational and should not be treated as a cryptographic trust anchor. A client that fetches a public configuration from the same gateway it is checking is using a trust-on-first- use convenience; pinning or independently reviewing the configuration is stronger.

What the system does not establish

  • A valid attestation proves that the configured threshold signed a digest and associated timestamp, not that the original document was submitted to the gateway.
  • A Merkle or RFC 9162 proof commits to log data and append-only extension; it does not make an operator's log globally canonical.
  • Federation adds independent signed observations of a batch root. It is not a Byzantine-fault-tolerant consensus protocol.
  • External anchors add provider-specific evidence. Their availability, retention, DNS behavior, log policy, or blockchain finality remain part of the operator's threat model.