Esiur Protocol (EP) Specification

1. Overview

The Esiur Protocol (EP) is a compact binary application-layer protocol for distributed object computing. It enables first-class sharing of object instances across a TCP or WebSocket connection: property values synchronize in real time, remote methods are called as if local, and events propagate transparently to every subscriber.

EP is fully self-describing: a client can discover the type schema of any resource at runtime (a TypeDef query) and generate strongly-typed proxies without out-of-band API documents. Actively maintained implementations exist for .NET and TypeScript, sharing wire concepts, packet layout, and command names byte-for-byte.

Key design properties:

• Minimal wire overhead — a 1-byte header is a complete, valid notification packet; request/reply packets add a 4-byte callback ID.
• Correlation-safe — every request carries a callback ID matched to its asynchronous reply.
• Streamable — chunked transfers, progress reports, and pausable pull/push streams for long-running operations.
• Authenticated by construction — every connection completes an authentication phase (possibly a no-op, see §4) before any session packet is exchanged.

2. Transport & URI scheme

TCP

EP runs natively over TCP. EpServer defaults to TCP port 10518 in both reference implementations; a bare ep://host URL (no explicit port) resolves to the same default. The server accepts incoming connections and immediately begins the Authentication Phase (§4).

WebSocket

EP also runs as a WebSocket sub-protocol, identifier EP (uppercase, compared case-sensitively/ordinally by both implementations). After the WebSocket handshake, the binary framing is identical to the TCP wire format: each WebSocket message carries exactly one EP packet.

URI scheme

Resources are addressed with an ep:// URL:

ep://<host>[:port]/<store>/<resource-path>

Examples
  ep://server.example.com/sys/thermostat
  ep://localhost:10518/sys/counter
  ep://iot-hub.local/sensors/temperature

The path maps directly to a resource in the server's store hierarchy, analogous to a filesystem path. Omitting the port uses 10518. A bare ep://host[:port] with no path resolves to the connection itself.

3. Connection lifecycle

Client                                        Server
  │                                               │
  │────────── TCP / WebSocket connect ───────────▶│
  │                                               │
  │◀─────── Auth: Initialize ─────────────────────│  server sends first
  │                                               │
  │──────── Auth: Action ─────────────────────────▶  zero or more rounds,
  │◀─────── Auth: Acknowledge ────────────────────│  protocol-dependent
  │                                               │
  │◀─────── Auth: SessionEstablished ─────────────│
  │                                               │
  │◀════════════ EP session packets ═════════════▶│
  │   Request / Reply / Notification              │
  │                                               │
  │────────── connection close ──────────────────▶│

Once the session is established, the connection is fully bidirectional — either peer may send Requests, Replies, or Notifications at any time. A resource attachment stays live until the connection closes or the client explicitly detaches; on reconnect, a client can reattach and resynchronize rather than re-fetch full state from scratch.

4. Authentication phase

Before any EP session packet is transmitted, both sides exchange one or more auth packets, a distinct binary format from session packets. The server always sends the first packet (Initialize). Even a connection configured for anonymous access completes this phase — it just negotiates AuthenticationMode.None with EncryptionMode.None in a single round trip.

4.1 Auth packet header byte

For every command other than Initialize, bits 4–0 (with bit 5 masked off) are instead read as a single EpAuthPacketMethod byte (§4.3) — the low 5 bits given above only apply to the very first, server-sent Initialize packet. hasTDU (bit 5) — when set, a TDU payload (§5) follows, encoding a key–value map of handshake parameters (§4.4).

4.2 Auth commands (bits 7–6)

AuthenticationMode (bits 3–2 of an Initialize packet):

EncryptionMode (bits 1–0 of an Initialize packet):

4.3 EpAuthPacketMethod (Acknowledge / Action / Event byte)

For any command other than Initialize, the byte identifies the specific handshake step:

4.4 Auth TDU header keys

The TDU payload of an auth packet is a keyed map. Integer keys 0–17 are defined:

5. TDU (Transmission Data Unit) encoding

Every value carried inside a session or auth packet — arguments, return values, property contents, handshake parameters — is encoded as a self-describing TDU. Decoders never need out-of-band schema information: each TDU carries its own type tag and, for variable-length types, its own length.

5.1 Identifier byte

For Dynamic, Typed, and Extension classes, the identifier recovered by a parser is headerByte & 0xC7 (class bits + sub-type bits only — the length-field-count bits are stripped once the length has been read). The length bytes themselves are big-endian (most-significant byte first):

5.2 Fixed class (0x00–0x2F)

Multi-byte Fixed-class payload contents (integers, floats, DateTime ticks) are little-endian — see §5.5 for verified examples. 128-bit integers are two little-endian 64-bit halves, low word first.

5.3 Dynamic class (0x40–0x47)

5.4 Typed & Extension classes

5.5 Verified wire examples

Each of these is a complete TDU (identifier byte, any length bytes, payload), taken from byte-for-byte matching test vectors shared between the .NET and TypeScript test suites:

The Int32/Int64 examples above intentionally show a multi-byte payload: note the least-significant byte comes first. This is the opposite byte order from the TDU length-prefix field (§5.1), which is big-endian — the two fields are independent and use different conventions.

6. EP packet format

After the authentication phase completes, all traffic uses EP session packets. Every packet begins with a single header byte; Request and Reply packets additionally carry a 4-byte callback ID. Payloads, when present, are TDU-encoded (§5).

Verified example — a KeepAlive request (no payload) with callback ID 12:

7. Commands reference

Request commands

Reply commands carry the Request's callback ID

Notification commands no callback ID — unsolicited

8. Implementation notes

EP is specified so that independent implementations interoperate over the wire without a translation layer, and the two reference implementations agree on every packet, command, and TDU value covered above. As of this writing, a few areas are implemented in one reference implementation but not (yet) the other:

None of this affects wire compatibility for the features both implementations do support today — it's listed here so implementers building a third party don't assume behavior that isn't universal yet.

9. Security considerations

• For any internet-facing deployment, use InitializerIdentity or DualIdentity authentication together with EncryptWithSessionKey (or EncryptWithSessionKeyAndAddress) encryption — or terminate the connection inside a TLS tunnel (a wss:// reverse proxy, or a TLS-wrapping proxy in front of raw TCP), since neither reference implementation currently wraps raw TCP in transport-layer TLS automatically (§8).
• Implementations parsing TDUs from an untrusted peer should enforce a maximum declared length before allocating a buffer for the length prefix described in §5.1 — an attacker-controlled length field is an obvious resource-exhaustion vector otherwise.
• A conforming WebSocket-hosting server should require and verify the negotiated subprotocol is exactly EP (ordinal, case-sensitive) before treating a connection as an EP session, even though not every implementation enforces this yet (§8).
• Stored password verifiers should be treated as sensitive as a plaintext password: under the password-sha3-v1 protocol, possessing the stored verifier is sufficient to authenticate.
• ppap-mlkem768-v1 is available where post-quantum resistance against key material is a requirement — see the PPAP paper [Zamil & Jasim, 2025] in §10.

10. References

• A. K. Zamil and A. D. Jasim, "A Multi-Factor Quantum-Resistant and Privacy-Preserving Authentication Protocol for Decentralized Systems," Mesopotamian Journal of CyberSecurity, vol. 5, no. 3, pp. 1272–1291, 2025. Accessed: Jul. 22, 2026. [Online]. Available: mesopotamian.press/journals/index.php/CyberSecurity/article/view/989 — the PPAP protocol behind ppap-mlkem768-v1 (§9)
• RFC 6455 — The WebSocket Protocol
• RFC 4122 — UUID layout, referenced by the TDU UUID type
• github.com/esiur/esiur-dotnet — reference implementation, .NET
• github.com/esiur/esiur-ts — reference implementation, TypeScript