`webtessera/witness`

A tlog-witness server, the other side of the witnessing in webtessera.

It has no Go counterpart: it is an addition of webtessera’s. Its source is src/witness/index.ts.

Functions

cosignerVkey: cosignerVkey returns the verifier key of the cosigner that newSignerForCosignatureV1(skey) builds: the cosignature/v1 (type 0x04) vkey that a witness publishes, that log operators put in their witness policies, and that newWitness and verifyReceipt's witness policies take.
coSigV1Timestamp: coSigV1Timestamp extracts the embedded timestamp from a CoSigV1 signature.
marshalAddCheckpointRequest: marshalAddCheckpointRequest encodes an add-checkpoint request body, for clients that submit checkpoints to a witness without going through an appender's witness gateway.
newSignerForCosignatureV1: newSignerForCosignatureV1 constructs a new Signer that produces timestamped cosignature/v1 signatures from a standard Ed25519 encoded signer key.
newVerifierForCosignatureV1: newVerifierForCosignatureV1 constructs a new Verifier for timestamped cosignature/v1 signatures from either a standard Ed25519 encoded verifier key, or an Ed25519 CosignatureV1 key.
newWitnessServer: newWitnessServer returns a witness: a server that cosigns the checkpoints of the logs it trusts, after checking that each is consistent with the last one it cosigned for the same log, as C2SP tlog-witness specifies.
originHash: originHash returns the lowercase hex SHA-256 of a log's origin, which is how the spec's monitoring endpoint names a log: "The origin hash is the SHA-256 hash of the log's origin, hex encoded, in lowercase."
parseAddCheckpointRequest: parseAddCheckpointRequest parses an add-checkpoint request body, throwing an error caused by ErrMalformedRequest if it does not follow the grammar exactly: The request body MUST be a sequence of - an old size line, - zero or more consistency proof lines, - and an empty line, - followed by a checkpoint[].
vKeyToCosignatureV1: vKeyToCosignatureV1 converts a standard Ed25519 vkey to an Ed25519CosignatureV1 vkey.

Classes

OldSizeMismatchError: OldSizeMismatchError reports the "409 Conflict" the spec prescribes when the old size does not match, with the size the client should retry from.
WitnessServer: WitnessServer is a tlog-witness witness.

Interfaces

AddCheckpointRequest: AddCheckpointRequest is the content of an add-checkpoint request.
InconsistencyEvidence: InconsistencyEvidence describes a validly signed checkpoint that the witness refused because it is inconsistent with what it cosigned before: what the spec calls "proof of log misbehavior", which a witness "MAY log".
LogKeys: LogKeys are the public keys a witness trusts to sign a log's checkpoints.
WitnessedLog: WitnessedLog is a log the witness is configured with up front.
WitnessServerOptions: WitnessServerOptions configures newWitnessServer.

Types

LogLookup: LogLookup finds the keys of a log the static configuration does not list, or resolves to undefined if the witness should not witness it.
WitnessStore: WitnessStore is the part of the ObjectStore contract the witness uses.

Constants and variables

ErrInvalidProof: ErrInvalidProof is the cause of every "422 Unprocessable Entity": a consistency proof that does not verify, a non-empty proof where the spec requires an empty one, or a checkpoint of size zero whose root is not the empty tree's.
ErrMalformedRequest: ErrMalformedRequest is the cause of every rejection the spec answers with "400 Bad Request": a body that does not follow the request grammar, a checkpoint that is not a well-formed note or checkpoint, or an old size larger than the checkpoint's.
ErrNoValidSignature: ErrNoValidSignature is the cause when no signature from a key trusted for the origin verifies, or one that names a trusted key fails to: the spec's "403 Forbidden".
ErrOldSizeMismatch: ErrOldSizeMismatch is the cause when the request's old size is not the size of the latest checkpoint the witness cosigned for the log.
ErrRootMismatch: ErrRootMismatch is the cause when the checkpoint has the size of the latest cosigned one but a different root hash: proof that the log presented two different trees of the same size. tlog-witness v1.0.0 answers it with "409 Conflict" (without the text/x.tlog.size body that distinguishes the old-size conflict); see docs/decisions/0171-witness-server.md for the later editor's draft that moves it to 422.
ErrUnknownLog: ErrUnknownLog is the cause when the witness has no keys for the checkpoint's origin: "If the checkpoint origin is unknown, the witness MUST respond with a "404 Not Found" HTTP status code."
MaxConsistencyProofLines: MaxConsistencyProofLines is the most proof lines a request may carry: "The client MUST NOT send more than 63 consistency proof lines." A consistency proof between trees of at most 2^64 leaves never needs more.