st-protocol

Binary wire protocol for Smart Tree daemon communication.

Overview

A tight, 6502-inspired binary protocol using control ASCII (0x00-0x1F) as opcodes. No JSON in the core path. Every byte means something.

Frame Format

┌──────┬─────────────────┬──────┐
│ verb │     payload     │ 0x00 │
│ 1B   │   N bytes       │ END  │
└──────┴─────────────────┴──────┘

Escape Sequences

0x1B 0x1B = literal 0x1B in payload
0x1B 0x00 = literal 0x00 in payload

Verb Map

0x01 SOH  SCAN         0x11 DC1  PERMIT
0x02 STX  FORMAT       0x12 DC2  DENY
0x03 ETX  SEARCH       0x13 DC3  ELEVATE
0x04 EOT  END_STREAM   0x14 DC4  AUDIT
0x05 ENQ  PING         0x15 NAK  ERROR
0x06 ACK  OK           0x16 SYN  SUBSCRIBE
0x07 BEL  ALERT        0x17 ETB  UNSUBSCRIBE
0x08 BS   BACK/UNDO    0x18 CAN  CANCEL
0x09 HT   CONTEXT      0x19 EM   M8_WAVE
0x0A LF   NEXT         0x1A SUB  REMEMBER
0x0B VT   STATS        0x1B ESC  ESCAPE
0x0C FF   CLEAR        0x1C FS   RECALL
0x0D CR   COMPLETE     0x1D GS   FORGET
0x0E SO   AUTH_START   0x1E RS   SESSION
0x0F SI   AUTH_END     0x1F US   USER

Network Addressing

Single byte prefix for routing:

0x00 = local daemon (Unix socket)
0x01-0x7F = cached host index
0x80-0xFE = inline address (len = byte - 0x80)
0xFF = broadcast/discover

Security Levels

Level 0x00: Read-only (SCAN, SEARCH, STATS) - no auth required
Level 0x01: Local write (FORMAT, temp files) - session required
Level 0x02: Mutate (EDIT, DELETE) - requires FIDO
Level 0x03: Admin (PERMIT, config) - requires FIDO + PIN

Usage

use st_protocol::{Frame, Verb, Payload};

// Create a PING frame (2 bytes)
let ping = Frame::ping();
let bytes = ping.encode(); // [0x05, 0x00]

// Create a SCAN frame
let scan = Frame::scan("/home/hue", 3);
let bytes = scan.encode();

// Decode a frame
let frame = Frame::decode(&bytes)?;
println!("{} {}", frame.verb().name(), frame.payload().as_str().unwrap_or(""));

License

MIT

st-protocol 0.1.0