Message catalog

This is the human-readable reference for every Nodus wire message. The packages/protocol zod schemas are the source of truth; this document is a language-neutral counterpart maintained alongside src/. Machine-readable JSON Schema equivalents are generated from the zod schemas via pnpm generate:schemas (see schemas/).

All messages share a common envelope before their type-specific payload:

{
  "type": "shard_upload",
  "schema_version": "1.0",
  "message_id": "uuid",
  "payload": { "...": "..." }
}

Field naming is snake_case on the wire throughout. TS consumers map to/from camelCase at the serialize/deserialize boundary.

Control MessagesCopy Anchor Link

registerCopy Anchor Link

Device/node identity announcement to the Relay, sent once when a device or node first connects. Used to establish presence and authorization.

heartbeatCopy Anchor Link

Liveness ping. Minimal payload; drives Relay-side presence (§13 Redis presence). A node/device is marked absent if no heartbeat arrives within the configured window.

node_auth_challengeCopy Anchor Link

Relay → Node, first frame after the node opens /ws (§8). The nonce is an opaque cryptographically random value with a 30-second TTL.

node_auth_responseCopy Anchor Link

Node → Relay, answering the challenge. The signature is Ed25519 over the exact challenge nonce bytes, made with the node's persistent identity key.

node_auth_resultCopy Anchor Link

Relay → Node, the outcome of challenge-response. message is human-readable; reason is a stable machine-readable code the Storage Node acts on (for example, it prints "Storage Node is not paired. Run: nodus node pair" for node_not_found instead of retrying a generic failure).

WebRTC Signaling MessagesCopy Anchor Link

These carry SDP/ICE payloads verbatim as opaque strings. The protocol layer does not validate SDP or candidate internals. from_peer/to_peer let the Relay route Path B signaling without inspecting payload contents (§5).

from_peer and to_peer are each either a device_id or a node_id.

webrtc_offerCopy Anchor Link

webrtc_answerCopy Anchor Link

webrtc_ice_candidateCopy Anchor Link

Transfer MessagesCopy Anchor Link

shard_uploadCopy Anchor Link

Carries metadata only — the actual encrypted shard bytes travel over HTTP (POST /buffer/upload) or a separate binary transport, referenced by transfer_id. This avoids base64-encoding up to 8 MB per shard in JSON (decision #2).

shard_ackCopy Anchor Link

Acknowledges receipt/verification of a shard. Ties into the file state machine (§23: NODE_RECEIVING → NODE_VERIFIED).

pending_notifyCopy Anchor Link

Relay → Node notification that a buffered shard is waiting for pickup (Path C, §13 relay buffer lifecycle). Sent when a client uploaded a shard via POST /buffer/upload while the target node was offline. Includes a fetch_token so the node can fetch the shard bytes over HTTP. The token is bound to the targeted node, and redemption is authenticated with that node's X-Nodus-* request signature as well as the bearer token.

tombstone_ackCopy Anchor Link

Node → Relay. Reports this node's progress on a tombstoned (soft-deleted) entity so the Tombstone view can show per-node status. Sent after applying a tombstone (deleted) and after permanently removing the data (purged). The node id is taken from the authenticated WS connection, never the payload.

purge_tombstoneCopy Anchor Link

Relay → Node. Ask the node to permanently remove a tombstoned entity's versions/shards/objects. The node replies with tombstone_ack{status:purged}.

restore_tombstoneCopy Anchor Link

Relay → Node. Undo a tombstone: the node deletes its tombstone row so retained data is not purged at the original retention deadline.

shard_fetchCopy Anchor Link

Request to retrieve a shard from a peer or the Relay buffer.

shard_deleteCopy Anchor Link

Request to delete a shard (e.g. post-transfer cleanup, or GC per §29a).

Design A shard stream (shard_fetch_request → binary frames)Copy Anchor Link

When the Relay must serve a browser download for a shard that lives on a Storage Node (no LAN host), it sends the node a shard_fetch_request envelope and the node answers with raw ciphertext outside the JSON envelope:

Relay → Node   shard_fetch_request { request_id, object_id }
Node  → Relay  shard_fetch_result  { request_id, object_id, status }
Node  → Relay  <binary frame>      [u8 version=1][u16be id_len][request_id][payload]  (0..n)
Node  → Relay  shard_fetch_done    { request_id }

A node may serve several requests concurrently over its single Relay socket, so binary frames from different fetches can interleave. Each binary frame therefore carries the routing request_id in a fixed header:

A frame whose version byte or length field is malformed, or whose request_id does not match a waiter assigned to the sending node, is dropped rather than misrouted. Relay and Storage Node must be upgraded together: the older per-connection framing is not supported (lockstep cutover).

A node must not send more bytes for one request_id than the shard it holds. The Relay records the encrypted shard's length in file_locations.size_bytes when the node reports the shard stored, uses it as the Content-Length of the browser download it is serving, and stops forwarding at it — so an oversized stream is cut short rather than proxied. The recorded length is a claim by the sending node, so it can only lower the Relay's limit; the ceiling is the configured MAX_SHARD_BYTES_MB plus per-shard encryption framing. The browser therefore sees a short read against a declared Content-Length, and its own shard-hash check rejects the result. A node that under-declares gets its own shard truncated.

Sync MessagesCopy Anchor Link

sync_helloCopy Anchor Link

Initial cursor-exchange handshake (§18). Sent when a node (or client) comes online to initiate incremental sync.

sync_statusCopy Anchor Link

Response to sync_hello. Each cursor adds a count so the sender can gauge how far behind it is.

event_batchCopy Anchor Link

Wraps one or more sync events (§15). See event-types.md for the complete event schema and payload shapes. This is where the "exact sync event schema" open item is finalized.

Both Storage Nodes and (Phase 14) authenticated devices may send event_batch. Both are validated server-side on the same three rules: every event's origin_id must equal the session peer id (the device_id or the node_id), its type must be in that peer's whitelist, and its origin_sequence must be strictly greater than the locked per-origin cursor. A batch that violates any of them is rejected whole and applies nothing.

The two whitelists differ in one type. A device may not claim FILE_SHARD_STORED — only a node reports that it has durably stored a shard. Everything else is shared: the set of types that has a projection in the Relay.

The per-event handling differs. A device batch is all-or-nothing down to the projection, because a device is interactive and can re-derive its state from the last_origin_sequence in the rejection. A node batch skips an individual unprojectable event and applies the rest, because a node's outbox is a durable ordered queue: one permanently-invalid row at the head would otherwise stall every later event behind it forever. Each node event runs in a savepoint, so a hard error in one event rolls back only that event.

batch_ackCopy Anchor Link

Acknowledges an event_batch. Node batches carry only applied_event_ids; device batches additionally carry the result fields.

reconcileCopy Anchor Link

Physical reconciliation signal (§21). Carries a content hash / manifest reference rather than full file lists — the receiver compares hashes and requests a full snapshot only on divergence.

Snapshot MessagesCopy Anchor Link

snapshot_beginCopy Anchor Link

Metadata for a full snapshot transfer (§20). The Relay validates the signature against the trusted node public key before accepting chunks.

cursors is a sibling of the field that is signed and is therefore not covered by the signature. The Relay validates the map itself and refuses the snapshot — at snapshot_begin, and again before any of it is written — if an entry has an empty origin_id, a negative sequence, a duplicated origin_id, or a sequence above the highest origin_sequence the Relay has itself accepted from that origin. Origins the Relay holds no events for are not bounded: after a factory reset the event log is empty and the node is the only remaining authority for its own state. A rejected map aborts the whole promotion rather than clamping, because the cursors decide which events replay.

snapshot_chunkCopy Anchor Link

Ordered chunk of snapshot data. Reassembled by chunk_index; retries reuse the same index for idempotency.

folder records (Phase 14 F1) carry folder_id, parent_folder_id, encrypted_name, and created_at, and let a Relay rebuild reconstruct the folder tree instead of leaving files with dangling parent references. key_envelope records (Phase 14 F2c) carry file_id, recipient_id, recipient_kind, and the opaque encrypted_key, so a rebuild preserves FEK envelopes.

snapshot_endCopy Anchor Link

Completion marker. The Relay validates final_hash against the hash promised in snapshot_begin before promoting the rebuilt state.

Error MessageCopy Anchor Link

A generic error/rejection envelope (decision #5). When a receiver cannot process a message, it responds with this instead of forcing every ack type to double as an error carrier.

Error codesCopy Anchor Link

validation_error, unknown_message_type, incompatible_version, not_found, rate_limited, internal_error, auth_failed.

Note the spelling of the last one: the wire value is auth_failed, not auth_failure. The relay has always sent auth_failed; auth_failure was a documentation error, and the ErrorCode enum now carries the relay's value under the AUTH_FAILURE key so the category still reads the same in code.

The snapshot path additionally uses these, all of them a retryable: false rejection of snapshot_begin:

All of the above are in the ErrorCode enum in packages/protocol/src/errors.ts, which is closed, so a code missing from it makes a client that strictly validates ErrorPayloadSchema reject an envelope it should have understood. A relay test (errorCodesEmittedByRelay in services/relay/internal/handler) fails if the relay emits a code that enum does not list, so the two cannot drift apart. The storage node does not parse error envelopes, so it is unaffected either way.

HTTP APIs (outside the WS envelope)Copy Anchor Link

A few endpoints are plain HTTP and do not use the envelope above. The bootstrap-pairing endpoints associate a first-time Storage Node with an account (§7b); the code is a one-time credential and never appears on the WebSocket.

POST /pairing/codes (authenticated)Copy Anchor Link

Mints a one-time pairing code for the signed-in account. Takes no body (the session cookie is the credential). Only the SHA-256 hash of the normalized code is stored; the plaintext is returned exactly once.

201 Created response:

POST /pairing/codes/redeem (open)Copy Anchor Link

Consumes a code and registers the presenting node under the issuing account, in one transaction (open — the code is the credential). The consume is atomic and single-use; a rejected registration rolls back so the code is not burned. IP rate-limited. The body is capped at 16 KiB. The registered Ed25519 key is immutable per node_id: re-registering with the same key is idempotent (key, status and is_primary preserved); a different key yields node_key_mismatch. The consumed row records the redeeming node_id.

200 OK → { "status": "ok", "account_id": "...", "is_primary": bool }.

Failures use {"error": "<reason>"}: