MessageTypeId Specification

4. MessageTypeId Specification

Purpose

Each message transmitted in the system must include a MessageTypeId, which uniquely defines:

• The purpose and semantic meaning of the message
• Its allowed direction (who may send and receive it)
• Its associated JSON Schema, used for validation
• Permission requirements that determine access control

This structure allows W3S to perform strict schema validation and role-based permission enforcement, reducing the risk of malformed, unauthorized, or spoofed messages.

---

Authorization Model

Every MessageTypeId is registered with:

• A known JSON Schema

• A set of allowed actors or roles (e.g., Sensor, Client, Admin)

• A defined directional constraint, such as:

  • OSS8 → W3S
  • W3S → Client
  • Client → W3S → OSS8

Each DeviceId has an associated role-based permission model that maps users (identified by their Zitadel ID) to roles, and roles to allowed MessageTypeIds and directions. Permissions are evaluated per device, enabling fine-grained access control.

At runtime, W3S uses this model to:

• Reject messages that violate schema or direction rules
• Reject or log unauthorized user actions based on role assignments
• Apply policy evaluation consistently across all message flows

---

Validation Process

Upon receiving a message, W3S performs the following steps:

1. Authentication Authentication is performed once during WebSocket upgrade using Zitadel token introspection. The authenticated Zitadel ID is bound to the tunnel and used to identify the sender for all subsequent messages.

2. Device ID Verification For OSS8 messages, the authenticated Zitadel ID must match the claimed DeviceId in the message. For client messages, the sender's role for the given DeviceId is checked before routing or handling.

3. MessageTypeId Lookup The MessageTypeId is used to retrieve its schema definition and permission constraints.

4. Schema Validation The Payload is validated against the registered schema. For binary messages, only the JSON header is validated.

5. Permission & Direction Check Based on the UserId, DeviceId, and MessageTypeId, W3S evaluates whether the action is allowed. This decision is made using the per-device role mapping and direction constraints.

6. Routing or Consumption Valid messages are forwarded, handled, or consumed as appropriate. Unauthorized or invalid messages are rejected or quarantined.

---

Binary MessageTypeIds

Some MessageTypeIds (e.g. OSS_IMAGE_FRAME) are used in messages with a binary payload. These follow the binary message framing format described in Section 3.

For these messages:

• Only the JSON header is validated against the schema
• The Payload section of the JSON header contains metadata describing the binary content
• Schema validation includes checking consistency between declared and actual image metadata

---

Versioning Strategy

• Each message includes a Version field to indicate the sender’s protocol version.

• W3S operates on a single canonical API version but supports backward compatibility within a controlled version range.

• When schema changes are breaking:

  • A new MessageTypeId is introduced with its own schema, or
  • Schema validation logic is version-aware and handles legacy formats explicitly.