The verifier

The verifier is a method, offered beside Quo. It is not Quo, and it is not the way to build a kit. It says where a kit departs from SPEC.md, and nothing else. It is necessary to show a kit departs from nothing, and it is never enough to show a kit is good, useful or finished.

A kit that answers every arrival with silence, or with nothing, departs from nothing and passes. The verifier reports how many arrivals it could judge, and a count is never a failure.

The verifier prints one line per check and a summary. It exits 0 when no check failed, and 1 when a check failed or it was run wrongly.

Checking, not comparing

The verifier takes bytes apart under SPEC.md. A check that holds for every correct box holds for a kit whatever it draws.

The sixteen bytes of silence are the one thing it compares, because SPEC.md fixes them. Nothing else a kit wrote is held against stored bytes.

As a tcp listener

The verifier dials the address listen answers:

• the kit writes nothing before a frame arrives, and may close an idle connection at any moment;
• an ask to a ward it stands comes back one of three ways. As a reply frame with the same id, whose box is judged as at arrive. As a nothing frame. Or not at all;
• an ask frame written one byte at a time is answered the same way, or the connection closes with it in flight and answers none;
• an ask frame of the largest body, 1,048,645, carries a box of the size;
• an ask frame with a ward pk and no box is a frame;
• an ask to a ward pk it does not stand comes back as a nothing frame with the same id;
• many asks in flight on one connection each come back once, in any order;
• after bytes that are not a frame, the kit closes the connection, and answers no ask written after them;
• a reply frame or a nothing frame sent to it is read, nothing is written back, and the connection stands;
• a whole relation runs over the line, a knock and the asks after it, each judged as at arrive. Among them stand a repeated number, a spent heir’s knock, and a key the door does not admit.

As a listener of the held line

The verifier opens a WebSocket to the address, offering the subprotocol quo:

• the kit selects quo, and a handshake that selects nothing fails;
• the kit sends no message before a frame arrives;
• an ask message to a ward it stands comes back one of three ways. As a reply message with the same id, whose box is judged as at arrive. As a nothing message. Or not at all;
• an ask message of the largest body, 1,048,645 bytes, carries a box of the size, and an ask message with a ward pk and no box is a frame;
• an ask to a ward pk it does not stand comes back as a nothing message with the same id;
• many asks in flight on one line each come back once, in any order;
• the kit closes the line after any of six messages, and answers no ask sent after it. A binary message longer than 1,048,645 bytes. One shorter than five. One of a kind that is none of the three. An ask with fewer than sixty-four bytes after its id. A nothing with bytes after its id. A text message;
• a reply message or a nothing message sent to it is read, nothing is sent back, and the line stands;
• a line that offers no subprotocol carries no frame: its handshake is refused, or an ask on it comes back as nothing at all;
• a whole relation runs over the line, as over tcp.

As a listener of the post

The verifier sends each ask as a POST to the address, its body the ward pk and the box:

• an ask to a ward it stands comes back as status 200 with a body, the reply’s box, judged as at arrive. Or it comes back as any other status, which is nothing;
• status 200 with an empty body is a departure;
• the Content-Type of the request changes nothing;
• an ask to a ward pk it does not stand comes back with a status other than 200;
• many posts in flight each come back;
• five requests each come back with a status other than 200 and 204. A GET. A PUT of a whole ask. A POST of no body, one of sixty-four bytes, and one of 1,048,641 bytes;
• a POST of 1,048,641 bytes whose connection closes before a status comes back is accepted, since a listener may answer a body too long before it reads the whole;
• a POST of sixty-five bytes is an ask, and one of 1,048,640 carries a box of the size;
• a whole relation runs over posts, as over tcp.

As a dialer

For each scheme the kit stands, the verifier holds a listener of its own, and routes a far ward to it with route. A web listener of the verifier’s answers at an address with a path and a query, and a request to any other path departs.

• On tcp, the kit’s first bytes on a connection are an ask frame, and it writes only ask frames.
• On the held line, the kit offers quo, and sends only binary ask messages.
• On the post, each ask is a POST to the address, with a body of sixty-five to 1,048,640 bytes.
• The ask carries the far ward’s pk, and its box is judged as at ask.
• On tcp and the held line, an ask frame sent to the kit is read, nothing comes back, and the connection stands.
• A reply, nothing, a closed connection and no answer at all each reach the kit, and the read it answers is checked. Nothing is a nothing frame on tcp and the held line, and any status other than 200 on the post.
• On the post, status 500, status 200 with an empty body, and status 201 with a reply’s box each read as nothing.
• A send to a ward with no route and no at reads nothing.
• After a second route for one far ward, no ask reaches the first address.

The invitation’s at

For each scheme the kit dials, the verifier mints an invitation from a ward no route names. Its at is a number, then an address of a scheme no carrier names, then an address of a listener of its own with its scheme in capitals. A reader skips the first two and reads the scheme in any case.

• A kit that reaches that listener is judged there as a dialer, over a whole relation.
• A kit that reaches nothing and reads nothing is accepted, since KIT-SPEC.md leaves reading at to the kit. The verifier prints whether the kit reached the ward through at, scheme by scheme.
• A kit that reaches the ward once and later reaches nothing departs, on one relation and across the schemes it dials.
• With a route and an at naming another address, the kit dials the route alone, and no connection reaches the address in at.

Windows

An ask with no answer at all is closed at once, and a kit that waits reads the close. Two windows remain, because a kit that writes nothing can only be seen not to write. One is how long the verifier listens for bytes that must not come, QUO_VERIFIER_QUIET_MS, 500 unless the environment names another. The other is how long a frame is held to arrive late, QUO_VERIFIER_LATE_MS, 1000 unless named. A kit’s own tests may set both near zero.

What no check derives

The six HKDF labels, quo-seal, quo-edge-seal, quo-lock, quo-edge, quo-ward-sign and quo-ward-seal, are the ASCII bytes of those names. Every HKDF-SHA-256 call takes the zero-length salt of RFC 5869. The fixed sizes stand as SPEC.md writes them. These stand on the text alone.

What the verifier does not see

Whatever a kit keeps, and how it keeps it, across a restart or across two copies of one ward. What a kit draws. How long a kit waits. How many arrivals a door judges at once, since a kit that judges one at a time answers two sent together as it answers two sent apart.

A domain’s vouch of DOMAIN.md. It is read for a person, and no door reads it, so no arrival shows whether a kit read one.

HARNESS

This is test tooling beside the protocol, offered as a method. It is not Quo, and it is not the way to build a kit. A kit that answers none of it still speaks Quo. Every term SPEC.md defines is used as SPEC.md defines it. Every other term is defined where it is introduced. Nothing here adds a byte to a box or a field to a payload.

Part one is what a kit answers to be judged without a carrier. Part two is what a kit answers to be judged with its bytes carried, to the verifier or to another kit.

The channel

Both directions are UTF-8. One JSON value is one line. A line ends with \n, and \r is not part of a line. No value carries a newline inside it. Answers come in any order, and id says which request each answers.

request = { id, op, ... }
answer  = { id, ... } | { id, error: <string> }

id is minted by the verifier, a string, unique among the requests in flight. op is a string, one of the requests this document names.

An error is one of these strings and no other:

no such op     op is none this document names
bad request    a line that is no JSON object, a field missing, null or of the
               wrong type, hex that is not lowercase hex of the right length,
               an invitation that is not one, or a request the kit does not
               serve
ward stood     a ward with that ward pk already stands
no such ward   ward names no ward this program stands
name held      heir names an heir this ward already holds
not reached    reach names nothing the kit provides

A line with no id, or an id that is not a string, is answered bad request with id set to null. An empty line is skipped. A channel line is plain JSON, and the value rules of SPEC.md do not apply to it.

Where two errors apply, the first in this order is the answer: bad request, no such op, no such ward, not reached, ward stood, name held.

stand runs until its stdin closes, and then exits. Exit 0 is a run that read its stdin to the end. Exit 1 is a run that could not start.

Nothing else is written on stdout. What a kit writes for its own eyes goes on stderr.

The six requests

{ id, op: "ward",    seed, reach? }               { id, ward: <128 hex> }
{ id, op: "invite",  ward, heir, reach? }         { id, invitation }
{ id, op: "release", ward, heir }                 { id, released: <string> | null }
{ id, op: "arrive",  ward, box }                  { id, reply: <hex> | null }
{ id, op: "ask",     ward, invitation, method?, args? }
                                                  { id, box: <hex> }
{ id, op: "read",    ward, invitation, reply }    { id, read }

ward stands a ward from seed. seed is text, taken as SPEC.md takes a seed that is not thirty-two bytes. It is hashed whatever its length. The answer is that ward’s ward pk.

In every other request, ward is the 128 hex ward pk of a ward this program stands.

invite holds a new heir of that ward under the name heir, a string the verifier chooses, and answers the invitation of SPEC.md. A released name may be invited again, and names a new heir.

release makes that ward stop holding the heir named heir. It answers that name, or null where the ward holds no heir of that name.

arrive delivers box, an ask’s box as hex, to that ward’s door. The answer is the reply’s box as hex, or null where the door gives back nothing.

ask makes that ward ask, as a standing, on the relation invitation names. The first ask on an invitation is a knock. method absent is the empty ask. args absent is the empty object. The answer is the box the kit sealed, as hex. The kit chooses every key it announces and every count number it sends. After a knock that brought no object back, a kit may answer ask on that invitation with the knock it sent before. It answers with the same bytes, whatever method and args ask.

read hands that ward reply, the reply’s box as hex, or null for nothing, as the answer to its last ask on that invitation. The answer read is what the kit read:

{ object, seen, at? }  an object came back
{ silence: true }      silence came back
{ quo: word }          a word came back
{ nothing: true }      nothing came back

object is the value the kit read, and seen the seen it read. at is present only for a kit that keeps addresses from a reply’s at. It holds those it kept, in their order, and is absent where the reply carried no array.

What answers behind a door

reach names what answers behind that door. How a kit provides it is the kit’s own. The verifier sends these five and no other:

echo     a named ask: the object is the bytes of `args` exactly as they
         arrived, or silence where the kit does not read that `args`.
         the empty ask: the object is the describe {"asks":[]}.
         seen is null, and no at is written.
marked   as echo, and on every ask seen is the string "1", the empty
         ask included.
moved    as echo, and every object carries at, the array
         ["tcp://127.0.0.1:9"].
null     a named ask: the object is null. seen is null.
         the empty ask: as echo.
silent   every ask: silence.

A reach that is none of the five, and that the kit does not provide, is answered not reached.

reach on ward names what answers the zero head at that ward. With no reach on ward, nothing answers the zero head there, and an ask on the zero head is case 4 of SPEC.md. reach on invite names what answers asks on that heir. With no reach on invite, it is echo.

The three requests

{ id, op: "listen", scheme? }                      { id, at: <address> }
{ id, op: "route",  far, at }                      { id, routed: <128 hex> }
{ id, op: "send",   ward, invitation, method?, args? }
                                                   { id, read }

listen makes the program hold one listener of scheme, tcp when absent, on a loopback address it chooses, and answer on it for every ward it stands. The answer is that listener’s address. A second listen of one scheme answers the same address. A scheme the kit does not stand is bad request.

invite, once the program holds a listener, may write that listener’s address, or any of its listeners’ addresses, in the invitation’s at.

route tells the program that the ward whose 128 hex ward pk is far is reached at at, one address. A second route for one far replaces the first. An at that is not an address, as the carrier of its scheme writes one, of a scheme the kit stands is bad request. far names a ward anywhere, and is not held to no such ward.

send makes that ward ask, as a standing, on the relation invitation names, and carry the box to the ward the invitation names. Where that ward has a route, the kit dials the route alone. Where it has none, a kit that reads at dials the addresses it holds for that ward, as it tries them. It holds them from the invitation’s at or a reply’s. A kit that does not read at delivers nothing. With neither, the ask is not delivered. The first send on an invitation is a knock. The answer read is what the kit read, as in part one. How long the kit waits is its own, and { nothing: true } is the answer when nothing came back.

Between two kits

The verifier stands a ward in one program and asks from a ward in another. It holds no kit. It routes the asking program’s far ward to an address of its own, or hands it an invitation whose at names that address. It forwards the frames to the answering program’s listener. Standing between them, it may deliver a frame as it came, late, twice, out of order, altered, or not at all. No kit implements any of that.

What the harness does not reach

How a kit keeps what it keeps, across a restart or across two copies of one ward, is the kit’s own, as KIT-SPEC.md asks. The harness names no partition, no restart and no copy. A door that forgets its relations departs from nothing.