Skip to content

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; auth may reach 4352 bytes to carry a 4096-byte token; data carries up to 65536 bytes of payload in at most 65600 bytes. Longer WebSocket messages are not read (status 1009).
  • Device authentication. After accept the relay sends a fresh 32-byte nonce; the client signs cloud-relay/v1/auth, a zero byte, the nonce and its Ed25519 device key. The connection then acts for that key. The nonce makes a captured auth useless 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 with auth-failed whatever 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, so max_devices counts devices rather than sessions.
  • Replay protection of control frames. create, claim and close carry a per-connection strictly increasing seq; a repeat or decrease closes the connection with replayed-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_channels limits open channels at once.
  • New reasons. auth-failed, device-not-allowed, unknown-request, request-expired, request-invalidated, code-mismatch, replayed-frame and peer-unavailable join the registry in cloud/protocol.
  • Retention. The relay's Store accepts 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/noise directly as the client-side session, since core/ 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_devices needs 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.