Gateway

witness-gateway is the coordinator and public HTTP server. It is a Rust/Axum binary backed by SQLite. It does not hold witness private keys; it uses the configured witness endpoints to request signature shares.

Startup and state

At startup the gateway:

1. reads and validates network.json;
2. rejects a witness set with a missing or empty auth_token;
3. opens SQLite in WAL mode and runs embedded, forward-only migrations;
4. initializes witness, federation, and anchor clients; and
5. starts the reconciler, batch manager, health/metrics tasks, and HTTP server.

The operational configuration includes secrets. The server's public network configuration projection omits witness and federation credentials.

Request groups

The implemented routes fall into these groups:

Group	Routes / purpose
Liveness and discovery	/health, /v1/config, /v1/network
Admission and status	POST /v1/attestations, GET /v1/attestations/:hash
Verification and proofs	POST /v1/verify, /v1/proof/:hash, /v1/bundle/:hash
Anchors	/v1/anchors/:hash, POST /v1/federation/anchor
Transparency log	/v1/log/sth, /v1/log/sth/:tree_size, /v1/log/consistency, /v1/log/proof
Operations	/metrics, optional /admin, /ws/events

Access control for these routes is partly application-level and partly a deployment concern. The gateway currently applies permissive CORS at the Axum router; a reverse proxy should enforce the intended network-level allowlists. Bearer authentication still applies to witness and federation operations.

Admission and deduplication

Admission validates the hash, performs the duplicate checks, applies the gateway's per-IP rate limit, optionally calls Freebird, and reserves the canonical SQLite job. The reservation and per-network sequence allocation use one transaction. On a duplicate, the sequence allocation is rolled back and the existing tuple is returned.

When a new reservation commits, the gateway immediately broadcasts an attestation WebSocket event containing the lowercase digest and reserved timestamp. This broadcast is independent of threshold confirmation and is unauthenticated by default unless WITNESS_WS_AUTH_TOKEN is configured.

Freebird is optional. In required mode, an absent or invalid token rejects the request. In consuming mode the gateway uses Freebird /v1/verify; in non-consuming mode it uses /v1/check. This is admission control, not a property of the attestation signature.

Aggregation and verification

The reconciler performs the fan-out and accepts only valid, unique responses. The gateway verifies individual responses before aggregation and verifies the final SignedAttestation again before persistence. This applies to both Ed25519 multi-signatures and BLS aggregates. A witness response that has the wrong ID or cannot be verified does not count toward the threshold.

The gateway's crypto and serialization implementation comes from witness-core; it does not define a second signing format.

Background responsibilities

                    +------------------+
new job ----------->| Reconciler       |----> confirmed attestation
                    +------------------+
                              |
                              v
                    +------------------+
confirmed jobs ---> | Batch manager    |----> batch + STH
                    +------------------+
                         |             |
                         v             v
                 Anchor manager   Federation client
                 external proofs  peer cross-anchors

The workers page describes lease and retry behavior in detail.

Outbound requests

Witness, federation, Freebird, and Internet Archive HTTP clients use the gateway's hardened HTTP client and resolver. Trillian and DNS anchor providers currently use unrestricted reqwest; Ethereum performs outbound URL preflight validation during initialization but its provider client is not the hardened client. Production URLs are expected to be HTTPS; plaintext loopback is an explicit development exception. Review provider-specific outbound behavior as an operational risk; the filter is defense in depth, not a universal SSRF guarantee or a replacement for network segmentation.

What the gateway can and cannot vouch for

The gateway can return signed and structurally linked records. Its local database and its remote verification endpoint are not independent evidence of honest operation. Clients can reduce this dependency by retaining signed objects, pinning public verification configuration, checking STH consistency, and using an independent auditor.