forked from ruvnet/RuView
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathrvf_parser.h
More file actions
135 lines (119 loc) · 5.42 KB
/
rvf_parser.h
File metadata and controls
135 lines (119 loc) · 5.42 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
/**
* @file rvf_parser.h
* @brief RVF (RuVector Format) container parser for WASM sensing modules.
*
* RVF wraps a WASM binary with a manifest (capabilities, budgets, schema),
* an Ed25519 signature, and optional test vectors. The ESP32 never accepts
* raw .wasm over HTTP when wasm_verify is enabled — only signed RVF.
*
* Binary layout (all fields little-endian):
*
* [Header: 32 bytes] [Manifest: 96 bytes] [WASM payload: N bytes]
* [Ed25519 signature: 0 or 64 bytes] [Test vectors: M bytes]
*
* Signature covers bytes 0 through (header + manifest + wasm - 1).
*/
#ifndef RVF_PARSER_H
#define RVF_PARSER_H
#include <stdint.h>
#include <stdbool.h>
#include "esp_err.h"
/* ---- Magic and version ---- */
#define RVF_MAGIC 0x01465652 /**< "RVF\x01" as u32 LE. */
#define RVF_FORMAT_VERSION 1
#define RVF_HEADER_SIZE 32
#define RVF_MANIFEST_SIZE 96
#define RVF_HOST_API_V1 1
#define RVF_SIGNATURE_LEN 64 /**< Ed25519 signature length. */
/* Raw WASM magic (for fallback detection). */
#define WASM_BINARY_MAGIC 0x6D736100 /**< "\0asm" as u32 LE. */
/* ---- Capability bitmask ---- */
#define RVF_CAP_READ_PHASE (1 << 0) /**< csi_get_phase */
#define RVF_CAP_READ_AMPLITUDE (1 << 1) /**< csi_get_amplitude */
#define RVF_CAP_READ_VARIANCE (1 << 2) /**< csi_get_variance */
#define RVF_CAP_READ_VITALS (1 << 3) /**< csi_get_bpm_*, presence, persons */
#define RVF_CAP_READ_HISTORY (1 << 4) /**< csi_get_phase_history */
#define RVF_CAP_EMIT_EVENTS (1 << 5) /**< csi_emit_event */
#define RVF_CAP_LOG (1 << 6) /**< csi_log */
#define RVF_CAP_ALL 0x7F
/* ---- Header flags ---- */
#define RVF_FLAG_HAS_SIGNATURE (1 << 0)
#define RVF_FLAG_HAS_TEST_VECTORS (1 << 1)
/* ---- Header (32 bytes, packed) ---- */
typedef struct __attribute__((packed)) {
uint32_t magic; /**< RVF_MAGIC. */
uint16_t format_version; /**< RVF_FORMAT_VERSION. */
uint16_t flags; /**< RVF_FLAG_* bitmask. */
uint32_t manifest_len; /**< Always RVF_MANIFEST_SIZE. */
uint32_t wasm_len; /**< WASM payload size in bytes. */
uint32_t signature_len; /**< 0 or RVF_SIGNATURE_LEN. */
uint32_t test_vectors_len; /**< 0 if no test vectors. */
uint32_t total_len; /**< Sum of all sections. */
uint32_t reserved; /**< Must be 0. */
} rvf_header_t;
_Static_assert(sizeof(rvf_header_t) == RVF_HEADER_SIZE, "RVF header must be 32 bytes");
/* ---- Manifest (96 bytes, packed) ---- */
typedef struct __attribute__((packed)) {
char module_name[32]; /**< Null-terminated ASCII name. */
uint16_t required_host_api; /**< RVF_HOST_API_V1. */
uint32_t capabilities; /**< RVF_CAP_* bitmask. */
uint32_t max_frame_us; /**< Requested budget per on_frame (0 = use default). */
uint16_t max_events_per_sec; /**< Rate limit (0 = unlimited). */
uint16_t memory_limit_kb; /**< Max WASM heap requested (0 = use default). */
uint16_t event_schema_version; /**< For receiver compatibility. */
uint8_t build_hash[32]; /**< SHA-256 of WASM payload. */
uint16_t min_subcarriers; /**< Minimum required (0 = any). */
uint16_t max_subcarriers; /**< Maximum expected (0 = any). */
char author[10]; /**< Null-padded ASCII. */
uint8_t _reserved[2]; /**< Pad to 96 bytes. */
} rvf_manifest_t;
_Static_assert(sizeof(rvf_manifest_t) == RVF_MANIFEST_SIZE, "RVF manifest must be 96 bytes");
/* ---- Parse result ---- */
typedef struct {
const rvf_header_t *header; /**< Points into input buffer. */
const rvf_manifest_t *manifest; /**< Points into input buffer. */
const uint8_t *wasm_data; /**< Points to WASM payload. */
uint32_t wasm_len; /**< WASM payload length. */
const uint8_t *signature; /**< Points to signature (or NULL). */
const uint8_t *test_vectors; /**< Points to test vectors (or NULL). */
uint32_t test_vectors_len;
} rvf_parsed_t;
/**
* Parse an RVF container from a byte buffer.
*
* Validates header magic, version, sizes, and SHA-256 build hash.
* Does NOT verify the Ed25519 signature (call rvf_verify_signature separately).
*
* @param data Input buffer containing the full RVF.
* @param data_len Length of the input buffer.
* @param out Parsed result with pointers into the input buffer.
* @return ESP_OK if structurally valid.
*/
esp_err_t rvf_parse(const uint8_t *data, uint32_t data_len, rvf_parsed_t *out);
/**
* Verify the Ed25519 signature of an RVF.
*
* @param parsed Result from rvf_parse().
* @param data Original input buffer.
* @param pubkey 32-byte Ed25519 public key.
* @return ESP_OK if signature is valid.
*/
esp_err_t rvf_verify_signature(const rvf_parsed_t *parsed, const uint8_t *data,
const uint8_t *pubkey);
/**
* Check if a buffer starts with the RVF magic.
*
* @param data Input buffer (at least 4 bytes).
* @param data_len Length of the buffer.
* @return true if the buffer starts with "RVF\x01".
*/
bool rvf_is_rvf(const uint8_t *data, uint32_t data_len);
/**
* Check if a buffer starts with raw WASM magic ("\0asm").
*
* @param data Input buffer (at least 4 bytes).
* @param data_len Length of the buffer.
* @return true if the buffer starts with WASM binary magic.
*/
bool rvf_is_raw_wasm(const uint8_t *data, uint32_t data_len);
#endif /* RVF_PARSER_H */