P4. PDU catalog and schemas

Work in progress — not audited

Normative protocol documentation for the current implementation. Not independently audited.

P4.1 Encoding

• All PDUs described here are sent over WebRTC data channels unless noted.
• Serialization: JSON encoded as UTF-8 text unless binary/Uint8Array fields are noted.
• Every PDU MUST include a string field type as the discriminator.
• Schema version: EnkryptedChat-Profile-v0 — field names may change before v1.0 freeze.

P4.2 PDU categories

Category	Purpose
Handshake	Establish encryptionReady
Encrypted transport	User content with encryptedMessage wrapper
Chunking	Split large ciphertext
Messaging	Cleartext routing metadata (payload may be encrypted inside wrapper)
Files	File transfer (standard and fast paths)
Calls	Group/voice/video signaling
Presence	Typing, peer list

P4.3 Handshake PDUs

type	Direction	Required fields (minimum)	Notes
mls-key-package-request	Either	—	Triggers key package send
mls-key-package	Either	keyPackage (implementation-defined)	MLS RFC 9420 structure
mls-encryption-sync-request	Either	—	State sync
mls-encryption-sync-response	Either	—	State sync response
signal-key-exchange-request	Either	Signal payload fields (WASM)	P2P X3DH start
signal-key-exchange-response	Either	Signal payload fields
signal-session-complete	Either	—	Signal ready
mlkem-key-exchange	Either	ML-KEM public key material
mlkem-key-exchange-response	Either	ML-KEM response
mls-commit	Either	MLS commit bytes / structure	Group ops
mls-welcome	Either	MLS welcome	New member
mls-welcome-ack	Either	—	Ack
rotation-timestamp-broadcast	Either	rotation timestamp	AES key rotation suffix
handshake	Either	—	Legacy/generic
protocol-error	Either	code number MUST; messageId string MAY; detail string MAY	See P8.8

P4.4 Encrypted message wrapper

User-visible chat uses outer PDU:

Field	Type	Required	Description
type	string	MUST	"message" for chat
encryptedMessage	object	MUST when E2EE on	See P4.5
callback	any	MAY	Implementation callback

Inner cleartext fields (before encryption) for message action:

Field	Type	Description
messageId	string	Unique id
message	string	Text body
timestamp	number	Unix ms
groupId	string	MAY — group route
attachment	object	MAY — media metadata

P4.5 encryptedMessage object

P4.5.1 Cascade mode (cascaded: true)

Field	Type	Required	Description
encrypted	boolean	MUST	true
cascaded	boolean	MUST	true
cascadedPayload	object	MUST	See P5
timestamp	number	MUST	Encryption time
chunked	boolean	MAY	true if split
messageId	string	MAY	Required if chunked
totalChunks	number	MAY	Chunk count
chunks	number[]	MAY	Byte arrays as JSON numbers

P4.5.2 MLS-only fallback (cascaded absent)

Field	Type	Required	Description
encrypted	boolean	MUST	true
envelope	object	MUST	groupId, epoch, ciphertext (byte array)
chunked	boolean	MAY	MLS chunking

MLS envelope fields:

Field	Type	Description
groupId	number[]	Byte array as JSON numbers
epoch	number	MLS epoch
ciphertext	number[]	MLS ciphertext bytes

P4.6 Chunk transport PDU

type	Fields	Description
__mls_chunk__	messageType, messageId, chunkIndex, totalChunks, chunk, envelope?, timestamp	Reassembles to full encryptedMessage

Reassembly MUST complete before decrypt. Out-of-order chunks SHOULD be buffered by chunkIndex.

P4.7 Messaging and presence PDUs

type	Purpose
message	Chat (see P4.4)
deleteMessage	Delete by messageId
typing-indicator	Typing state
peer-list	Known peers
peer-joined	Peer presence
group-member-joined	Group membership
group-invite	Group invite

P4.8 File transfer PDUs (standard path)

type	Purpose
file-metadata	Start transfer
request-chunk	Request chunk index
file-chunk	Chunk payload
chunk-received	Ack
file-transfer-complete	Done
chunk-ack	Ack variant

P4.9 File transfer PDUs (fast path)

Used when fast file transfer is enabled; cascade MAY be bypassed.

type	Purpose
chunk-request	Request chunk
file-chunk	Data
byte-range-request	Range request
byte-range-response	Range response
transfer-verify-request	Verify
transfer-verify-response	Verify response
transfer-chunk-status-request	Status
transfer-chunk-status-response	Status response
transfer-complete-notify	Complete
transfer-complete-verify	Verify complete
missing-data-response	Missing data
fast-file-metadata	Fast path metadata (same role as file-metadata)

Chunk sizes: 1 MB–16 MB adaptive (useFastFileTransfer); per-message cap 256 KB metadata overhead in some paths.

P4.10 Call PDUs

type	Purpose
groupCallRequest	Incoming group call
groupCallAccepted	Accepted
groupCallEnded	Ended
call-ended	1:1 call end

Media uses WebRTC SRTP; optional SFrame layer — experimental (ch. 4).

P4.11 Unknown types

Receivers MUST drop unknown type values without crashing; MAY log at debug only. Senders MUST NOT send handshake PDUs after encryptionReady except for rotation or group maintenance.

P4.12 Global PDU fields

Field	Type	Required	Max / notes
type	string	MUST	Discriminator; see tables below
specVersion	string	MAY	MUST in Profile-v1; value "1.0"

Total serialized PDU size MUST NOT exceed 16 MiB (P8).

P4.13 Complete PDU field reference

Extracted from p2p routing (MLSProvider.tsx) and p2p/src/features/. WASM/MLS binary blobs are opaque string or number[] on the wire.

Handshake and crypto control

type	Fields (name · type · required)
mls-key-package-request	— (no additional fields)
mls-key-package	keyPackage · string/object · MUST
mls-encryption-sync-request	implementation-defined · MAY
mls-encryption-sync-response	implementation-defined · MAY
signal-key-exchange-request	Signal WASM payload · MUST · Appendix B
signal-key-exchange-response	Signal WASM payload · MUST
signal-session-complete	— · MAY
mlkem-key-exchange	ML-KEM public key material · MUST
mlkem-key-exchange-response	ML-KEM response · MUST
mls-commit	MLS commit bytes/structure · MUST
mls-welcome	MLS welcome · MUST
mls-welcome-ack	— · MAY
rotation-timestamp-broadcast	rotationTimestamp · number · SHOULD
handshake	legacy · MAY

Messaging and presence

type	Fields
message	messageId string SHOULD · message string MAY · timestamp number MAY · groupId string MAY · attachment object MAY · encryptedMessage object MUST when E2EE · originalSender string MAY (relay) · _senderId string MAY
deleteMessage	messageId string MUST · groupId string MAY
typing-indicator	indicatorType string SHOULD (typing, recording-audio, sharing-location, stopped) · chatId string MAY
peer-list	peer list payload · implementation-defined
peer-joined	peerId string SHOULD
group-member-joined	groupId string MUST · member fields · implementation-defined
group-invite	groupId string MUST · invite payload · implementation-defined

Chunk transport

type	Fields
__mls_chunk__	messageId MUST · chunkIndex MUST · totalChunks MUST · chunk number[] MUST · messageType MAY · timestamp MAY · envelope object MAY (MLS chunk path)

Standard file transfer

type	Fields
file-metadata	fileId MUST · fileName MAY · fileSize number MAY · mimeType string MAY · totalChunks number MAY · prefix string MAY · thumbnail string/object MAY · groupId string MAY
fast-file-metadata	same as file-metadata
request-chunk	fileId MUST · chunkIndex number MUST · requestedSize number MAY · groupId string MAY · originalRequester string MAY
file-chunk	fileId MUST · chunkIndex number MUST · chunk number[]/binary MUST · groupId string MAY
chunk-received	fileId MUST · chunkIndex number MUST
chunk-ack	ack fields · implementation-defined
file-transfer-complete	fileId MUST · completion metadata MAY

Fast file transfer

type	Fields
chunk-request	fileId MUST · chunkIndex number MUST · requestedSize number MAY
byte-range-request	range fields · implementation-defined
byte-range-response	range + data · implementation-defined
transfer-verify-request	fileId MUST · verify metadata MAY
transfer-verify-response	verify result · implementation-defined
transfer-chunk-status-request	status query · implementation-defined
transfer-chunk-status-response	status result · implementation-defined
transfer-complete-notify	fileId MUST
transfer-complete-verify	verify complete · implementation-defined
missing-data-response	missing chunk indices · implementation-defined

Calls

type	Fields
groupCallRequest	callType string MUST · groupId string MAY · callerName string MAY · originalCaller string MAY · relayedBy string MAY
groupCallAccepted	group/call ids · implementation-defined
groupCallEnded	group/call ids · implementation-defined
call-ended	from string MAY (peer id)

| protocol-error | code MUST · messageId MAY · detail MAY (no secrets) |

protocol-error (Profile-v0 implemented)

Field	Type	Required	Notes
type	string	MUST	"protocol-error"
code	number	MUST	1–5 per P8.8
messageId	string	MAY	Related message
detail	string	MAY	Debug only; no secrets

Relay metadata (group PDUs)

Group relay PDUs MAY include: originalSender, _senderId, relayedBy (string). Receivers SHOULD use originalSender for routing when present.

P4.14 Source of truth

PDU handlers are centralized in MLSProvider.tsx (routing) and feature modules under p2p/src/features/. This catalog reflects that implementation as of profile v0. See ch. 10 for repository map.