0023: Relay authentication, pairing and forwarding wire
- Status: proposed
- Date: 2026-09-25
The number was assigned at merge of the add-cloud-service proposal's
task group 3 into staging (this file was
XXXX-relay-pairing-and-forwarding-wire.md until then).
Context
Task group 3 of add-cloud-service implements the relay module. The relay and cloud specs require outbound-only WebSocket connections, token presentation after version negotiation, device-code pairing with a short code and a request id, rate limits on creation and on failed claims, opaque forwarding between device keys, and metadata-only retention with address hashes keyed daily. They do not fix the frames after negotiation, how a connection proves its device key, what an allowlist admits, how channels are counted for tokens, or where the persistent relay store comes from. The test author chose them; this records the choices for review.
Decision
- Frames. The frames after negotiation (challenge, auth, ready,
create, created, claim, claimed, paired, data, close, ended, error)
are canonical CBOR maps like the negotiation frames, defined in
docs/protocol/relay-v1.md and implemented by
cloud/relay/wire. They are part of relay version 1.0, which had not been released. - Sizes. Control frames stay at 4096 bytes;
authmay reach 4352 bytes to carry a 4096-byte token;datacarries up to 65536 bytes of payload in at most 65600 bytes. Longer WebSocket messages are not read (status 1009). - Device authentication. After
acceptthe relay sends a fresh 32-byte nonce; the client signscloud-relay/v1/auth, a zero byte, the nonce and its Ed25519 device key. The connection then acts for that key. The nonce makes a capturedauthuseless on any other connection. A device key that encodes a point of small order (the identity and the points of order 2, 4 and 8, including their non-canonical encodings) is refused withauth-failedwhatever the signature: Ed25519 verification accepts such keys, and for some of them a fixed signature verifies for every message. - Modes. Open (default, no configuration), allowlist
(
VAULTFOLD_CLOUD_RELAY_ALLOWLIST, every connecting key must be listed) or token (VAULTFOLD_CLOUD_TOKEN_ISSUER); setting both is a configuration error. In open and allowlist modes a token is ignored. Clients use one stable key per device, somax_devicescounts devices rather than sessions. - Replay protection of control frames.
create,claimandclosecarry a per-connection strictly increasingseq; a repeat or decrease closes the connection withreplayed-frame. Payload replay protection stays end to end, inside the clients' Noise session. - Pairing. Request ids are 16 random bytes. Codes are four letters from the 23 letters without I, L and O, a dash and four digits (about 31.4 bits), drawn by rejection sampling and unique among pending requests. A claim carries the request id and the code, or only the code (typed fallback). Wrong codes count per request; the fifth (configurable) invalidates it and tells the requester. Failed claims also count per connection; while that allowance is used up every claim from the connection is refused unchecked. Pending requests expire after five minutes by default.
- Channels and tokens. A pending or paired request is one open
channel of the requester's token id and of the claimer's;
max_channelslimits open channels at once. - New reasons.
auth-failed,device-not-allowed,unknown-request,request-expired,request-invalidated,code-mismatch,replayed-frameandpeer-unavailablejoin the registry incloud/protocol. - Retention. The relay's
Storeaccepts only device, request and connection records whose fields are device keys, token ids, request ids, keyed address hashes, timestamps and sizes; records are pruned after 30 days by default. Address hashes are HMAC-SHA256 under a key drawn per UTC day and discarded at rotation. This group delivers the interface and an in-memory store; the persistent relay datastore implements the same interface when a later group (the read audit log of group 4 is the first that needs durable relay rows) adds it. - Noise in tests. The relay never imports a Noise implementation. The
tests use
github.com/flynn/noisedirectly as the client-side session, sincecore/has no Noise package yet; the client daemon's session belongs to the agent daemon change.
Consequences
- Any client can implement the relay from docs/protocol/relay-v1.md
alone; the Go client is
cloud/relay/client. - A self-hosted relay with an allowlist requires the remote requester to hold an allowlisted key too.
- Restarting the relay loses pending requests and the day's address key, which is acceptable: requests are short-lived and the key must not persist.
Alternatives considered
- Identifying a connection by the token alone. Rejected: allowlist mode
has no token, and
max_devicesneeds a device identity. - Claim by request id alone, with the code only displayed. Rejected: the spec counts failed code attempts per request, which needs the code in the claim.
- Counting channels ever opened under a token rather than open ones. Rejected: an attenuated one-channel token would then be single-use.