Outer Envelope

Every frame is JSON with explicit field names:

• version
• messageId
• senderAccountId
• recipientAccountId
• senderDeviceToken
• timestamp
• expiryTimestamp
• nonce
• messageType
• encryptedPayload
• signature

Supported Optional Extension Fields

• recipientDeviceToken
• payloadProtection
• registrationPublicEncryptionKey
• registrationPublicSigningKey
• ackMessageId
• errorCode
• errorMessage
• restorationApproval

Message Types

• REGISTER
• HEARTBEAT
• COMMAND
• STATUS
• ACK
• ERROR

Inner Payload

The inner payload is JSON with:

• payloadVersion
• payloadType
• eventType
• body
• ackMessageId
• errorCode
• errorMessage
• publicEncryptionKey
• publicSigningKey

Supported Event Types

• WIPE
• LOCK
• ALERT
• CHECK_IN
• STATUS_SYNC

Encryption Rules

• COMMAND and STATUS payloads are encrypted with recipient RSA public keys using RSA_OAEP_SHA256.
• REGISTER, HEARTBEAT, and ACK use payloadProtection = NONE.
• Control payloads remain plaintext-by-design because the relay must validate routing and registration metadata without device private keys.
• Private device actions and status contents stay inside the encrypted inner payload.

What Is Signed

The Ed25519 signature covers the canonical string built from:

• version
• messageId
• senderAccountId
• recipientAccountId
• senderDeviceToken
• recipientDeviceToken
• timestamp
• expiryTimestamp
• nonce
• messageType
• encryptedPayload
• payloadProtection
• registrationPublicEncryptionKey
• registrationPublicSigningKey
• ackMessageId
• errorCode
• errorMessage
• Restoration approval metadata when present

This is signed so an attacker cannot tamper with:

• Routing metadata
• Ciphertext
• Expiry rules
• Replay material
• Registration keys
• Acknowledgements
• Restoration approval claims

Signing the ciphertext instead of the decrypted plaintext keeps the relay and clients aligned on exactly the same bytes over the wire.

Validation Rules

• Reject unknown version.
• Reject missing required outer fields.
• Reject timestamps outside the allowed skew window.
• Reject expired frames.
• Reject duplicate nonces within the replay TTL.
• Reject invalid signatures.
• Reject COMMAND and STATUS frames that do not declare RSA_OAEP_SHA256.
• Reject REGISTER frames without explicit public keys.

Upgrade Compatibility

• version is mandatory and must be checked before processing.
• Unknown optional fields must be ignored.
• New protocol versions should only add optional fields before removing or redefining any existing field.
• Inner payloads also have their own payloadVersion, so payload evolution does not force an outer envelope rewrite.