UEPS Protocol

The ueps package implements the Universal Encrypted Payload System -- a consent-gated TLV (Type-Length-Value) wire protocol with HMAC-SHA256 integrity verification.

TLV Tag Registry

Each TLV field uses a 1-byte tag, 1-byte length (max 255 bytes per field), and variable-length value:

Tag	Constant	Size	Description
`0x01`	`TagVersion`	1 byte	Protocol version (default `0x09` for IPv9)
`0x02`	`TagCurrentLay`	1 byte	Current network layer
`0x03`	`TagTargetLay`	1 byte	Target network layer
`0x04`	`TagIntent`	1 byte	Semantic intent token (routes the packet)
`0x05`	`TagThreatScore`	2 bytes	Threat score (0--65535, big-endian uint16)
`0x06`	`TagHMAC`	32 bytes	HMAC-SHA256 signature
`0xFF`	`TagPayload`	variable	Application data (read until EOF)

Header

The UEPSHeader struct carries conscious routing metadata:

type UEPSHeader struct {
    Version      uint8   // Default 0x09
    CurrentLayer uint8   // Source layer
    TargetLayer  uint8   // Destination layer
    IntentID     uint8   // Semantic intent token
    ThreatScore  uint16  // 0-65535
}

Building Packets

PacketBuilder constructs signed UEPS frames:

builder := ueps.NewBuilder(intentID, payload)
builder.Header.ThreatScore = 100
frame, err := builder.MarshalAndSign(sharedSecret)

NewBuilder sets defaults: version 0x09, both layers to 5 (Application), threat score to 0 (assumed innocent).

MarshalAndSign serialises header TLVs (tags 0x01--0x05), computes the HMAC-SHA256 over the serialised headers plus the raw payload, writes the HMAC TLV (0x06), and appends the payload after the 0xFF tag marker.

The HMAC covers: header TLVs (as bytes) + payload (raw). It does NOT cover the 0xFF tag byte or the HMAC TLV itself.

Reading and Verifying

ParsedPacket holds the verified result:

type ParsedPacket struct {
    Header  UEPSHeader
    Payload []byte
}

ReadAndVerify(reader, sharedSecret) reads a UEPS frame from a buffered reader:

Reads TLV fields sequentially, accumulating header bytes into a signed-data buffer
Stores the HMAC signature separately (not added to signed-data)
On encountering 0xFF, reads remaining bytes as payload
Recomputes HMAC over signed-data + payload
Returns ParsedPacket if signatures match, or an integrity violation error

On HMAC mismatch, the reader returns: "integrity violation: HMAC mismatch (ThreatScore +100)".

Intent Routing

The IntentID field enables semantic routing at the application layer. Reserved intent values:

ID	Purpose
`0x01`	Handshake / Hello
`0x20`	Compute / Job Request
`0x30`	Rehab / Intervention (benevolent intervention axiom)
`0xFF`	Extended / Custom (sub-protocols in payload)

The dispatcher (node/dispatcher.go) contains the routing skeleton for UEPS packets, including a threat circuit breaker that drops packets with ThreatScore > 50000.

See Node-Architecture for the high-level P2P mesh that operates above the UEPS wire protocol.