@meshcore-cz/meshpkt 0.1.1 → 0.1.3

package/README.md

@@ -5,6 +5,8 @@
 
 MeshCore radio packet codec for JavaScript and TypeScript, powered by WebAssembly.
 
+> **Early development.** This package is a work in progress. APIs may change before v1.0 — pin to a specific version in production.
+
 - **npm:** [npmjs.com/package/@meshcore-cz/meshpkt](https://www.npmjs.com/package/@meshcore-cz/meshpkt)
 - **Go source & docs:** [pkg.go.dev/github.com/meshcore-cz/meshpkt](https://pkg.go.dev/github.com/meshcore-cz/meshpkt)
 
@@ -113,20 +115,31 @@ console.log(msg.destHash); // first-byte hash of recipient's public key
 
 ### Node advertisements (ADVERT)
 
+The signature is verified automatically. `decodeAdvert` returns `{ error }` if
+the packet carries a non-zero signature that does not verify — tampered data is
+rejected before you ever see the fields.
+
 ```ts
 const env = meshpkt.decodeEnvelope(rawHex);
 if ("error" in env || env.type !== "ADVERT") return;
 
 const adv = meshpkt.decodeAdvert(env.payloadHex);
-if ("error" in adv) throw new Error(adv.error);
+if ("error" in adv) throw new Error(adv.error); // also catches bad signatures
 
-console.log(adv.name);      // "CZ.NIC Repeater"
-console.log(adv.nodeType);  // 2 = repeater
+console.log(adv.name);        // "CZ.NIC Repeater"
+console.log(adv.publicKey);   // 64-char hex — treat this as the stable identity
+console.log(adv.nodeType);    // 2 = repeater
+console.log(adv.sigVerified); // true = Ed25519 signature verified
+                              // false = all-zero signature (unsigned packet)
 if (adv.hasGPS) {
   console.log(adv.lat, adv.lon);
 }
 ```
 
+> **Note:** `sigVerified: true` proves the holder of `publicKey` signed exactly
+> this name and these coordinates. It does not prove the name is unique — use
+> `publicKey` as the stable identity, and treat the name as a signed label.
+
 ---
 
 ### Key utilities

package/dist/wasm.gen.d.ts

@@ -41,6 +41,7 @@ export interface AdvertPayload {
     hasGPS: boolean;
     lat?: number;
     lon?: number;
+    sigVerified: boolean;
 }
 export interface AckPayload {
     crc: number;
@@ -87,6 +88,23 @@ export interface ControlPayload {
     discoverSNR?: number;
     discoverPubKey?: string;
 }
+export interface TracePayload {
+    tag: number;
+    authCode: number;
+    flags: number;
+    hashWidth: number;
+    routeHashes: string[];
+    snrs: string[];
+    hopCount: number;
+}
+export interface MultipartPayload {
+    remaining: number;
+    innerType: string;
+    innerTypeCode: number;
+    innerPayloadHex: string;
+    ackCrc?: number;
+    ackCrcHex?: string;
+}
 export interface KeypairResult {
     publicKey: string;
     privateKey: string;
@@ -102,6 +120,8 @@ export interface MeshcoreWasm {
     encodeReq(privKey: string, peerPubKey: string, reqType: number, data: string): HexResult | ErrResult;
     encodeAnonReq(destPubKey: string, myPrivKey: string, data: string): HexResult | ErrResult;
     encodeDiscoverReq(typeFilter: number, tag: number, since: number, prefixOnly: number): HexResult | ErrResult;
+    encodeTrace(tag: number, authCode: number, flags: number, routeHashes: string): HexResult | ErrResult;
+    encodeMultipartAck(remaining: number, crc: number): HexResult | ErrResult;
     encodeRaw(route: number, payloadType: number, version: number, pathHashSize: number, payload: string): HexResult | ErrResult;
     decodeEnvelope(packet: string): Envelope | ErrResult;
     decodeGroupText(payload: string, channelName: string): GroupTextPayload | ErrResult;
@@ -116,11 +136,13 @@ export interface MeshcoreWasm {
     decodePath(payload: string, privKey: string, peerPubKey: string): PathPayload | ErrResult;
     decodeAnonReq(payload: string, myPrivKey: string): AnonReqPayload | ErrResult;
     decodeControl(payload: string): ControlPayload | ErrResult;
+    decodeTrace(packet: string): TracePayload | ErrResult;
+    decodeMultipart(payload: string): MultipartPayload | ErrResult;
     generateKeypair(): KeypairResult | ErrResult;
     deriveChannelSecret(channelName: string): HexResult | ErrResult;
     sharedSecret(privKey: string, peerPubKey: string): HexResult | ErrResult;
 }
-export declare const meshcoreOpNames: readonly ["encodeGroupText", "encodeGroupTextSecret", "encodeGrpData", "encodeGrpDataSecret", "encodeDirectText", "encodeAdvert", "encodeAck", "encodeReq", "encodeAnonReq", "encodeDiscoverReq", "encodeRaw", "decodeEnvelope", "decodeGroupText", "decodeGroupTextSecret", "decodeDirectText", "decodeAdvert", "decodeAck", "decodeGrpData", "decodeGrpDataSecret", "decodeReq", "decodeResponse", "decodePath", "decodeAnonReq", "decodeControl", "generateKeypair", "deriveChannelSecret", "sharedSecret"];
+export declare const meshcoreOpNames: readonly ["encodeGroupText", "encodeGroupTextSecret", "encodeGrpData", "encodeGrpDataSecret", "encodeDirectText", "encodeAdvert", "encodeAck", "encodeReq", "encodeAnonReq", "encodeDiscoverReq", "encodeTrace", "encodeMultipartAck", "encodeRaw", "decodeEnvelope", "decodeGroupText", "decodeGroupTextSecret", "decodeDirectText", "decodeAdvert", "decodeAck", "decodeGrpData", "decodeGrpDataSecret", "decodeReq", "decodeResponse", "decodePath", "decodeAnonReq", "decodeControl", "decodeTrace", "decodeMultipart", "generateKeypair", "deriveChannelSecret", "sharedSecret"];
 export declare const RouteTypes: readonly [{
     readonly code: 0;
     readonly label: "TRANSPORT_FLOOD";

package/dist/wasm.gen.js

@@ -11,6 +11,8 @@ export const meshcoreOpNames = [
     "encodeReq",
     "encodeAnonReq",
     "encodeDiscoverReq",
+    "encodeTrace",
+    "encodeMultipartAck",
     "encodeRaw",
     "decodeEnvelope",
     "decodeGroupText",
@@ -25,6 +27,8 @@ export const meshcoreOpNames = [
     "decodePath",
     "decodeAnonReq",
     "decodeControl",
+    "decodeTrace",
+    "decodeMultipart",
     "generateKeypair",
     "deriveChannelSecret",
     "sharedSecret",
@@ -727,6 +731,130 @@ export const OpMetas = [
             { name: "hex", kind: "string", optional: false, label: "Hex packet" },
         ],
     },
+    {
+        name: "encodeTrace",
+        category: "encode",
+        label: "Encode TRACE",
+        tabGroup: "trace",
+        tabGroupLabel: "TRACE",
+        tabGroupSub: "path trace",
+        tabGroupDoc: "",
+        tabLabel: "",
+        packetType: "",
+        resultTypeName: "HexResult",
+        params: [
+            {
+                name: "tag",
+                kind: "int",
+                label: "Tag (random)",
+                placeholder: "0",
+                optional: false,
+                choices: [],
+                showWhen: "",
+                showValue: 0,
+                group: "",
+                action: "",
+                widget: "",
+                autoFill: "",
+                secret: false,
+            },
+            {
+                name: "authCode",
+                kind: "int",
+                label: "Auth code (opaque)",
+                placeholder: "0",
+                optional: false,
+                choices: [],
+                showWhen: "",
+                showValue: 0,
+                group: "",
+                action: "",
+                widget: "",
+                autoFill: "",
+                secret: false,
+            },
+            {
+                name: "flags",
+                kind: "int",
+                label: "Flags (hash width: 0=1B 1=2B 2=4B 3=8B)",
+                placeholder: "0",
+                optional: false,
+                choices: [],
+                showWhen: "",
+                showValue: 0,
+                group: "",
+                action: "",
+                widget: "",
+                autoFill: "",
+                secret: false,
+            },
+            {
+                name: "routeHashes",
+                kind: "hex",
+                label: "Route hashes (hex)",
+                placeholder: "",
+                optional: true,
+                choices: [],
+                showWhen: "",
+                showValue: 0,
+                group: "",
+                action: "",
+                widget: "textarea",
+                autoFill: "",
+                secret: false,
+            },
+        ],
+        result: [
+            { name: "hex", kind: "string", optional: false, label: "Hex packet" },
+        ],
+    },
+    {
+        name: "encodeMultipartAck",
+        category: "encode",
+        label: "Encode MULTIPART ACK",
+        tabGroup: "multipart",
+        tabGroupLabel: "MULTIPART",
+        tabGroupSub: "repeated ACK",
+        tabGroupDoc: "",
+        tabLabel: "",
+        packetType: "",
+        resultTypeName: "HexResult",
+        params: [
+            {
+                name: "remaining",
+                kind: "int",
+                label: "Remaining (packets still to send after this)",
+                placeholder: "0",
+                optional: false,
+                choices: [],
+                showWhen: "",
+                showValue: 0,
+                group: "",
+                action: "",
+                widget: "",
+                autoFill: "",
+                secret: false,
+            },
+            {
+                name: "crc",
+                kind: "int",
+                label: "ACK CRC32",
+                placeholder: "0",
+                optional: false,
+                choices: [],
+                showWhen: "",
+                showValue: 0,
+                group: "",
+                action: "",
+                widget: "",
+                autoFill: "",
+                secret: false,
+            },
+        ],
+        result: [
+            { name: "hex", kind: "string", optional: false, label: "Hex packet" },
+        ],
+    },
     {
         name: "encodeRaw",
         category: "encode",
@@ -813,7 +941,6 @@ export const OpMetas = [
                     { value: 1, label: "1" },
                     { value: 2, label: "2" },
                     { value: 3, label: "3" },
-                    { value: 4, label: "4" },
                 ],
                 showWhen: "",
                 showValue: 0,
@@ -1092,6 +1219,7 @@ export const OpMetas = [
             { name: "hasGPS", kind: "boolean", optional: false, label: "Has GPS" },
             { name: "lat", kind: "number", optional: true, label: "Latitude" },
             { name: "lon", kind: "number", optional: true, label: "Longitude" },
+            { name: "sigVerified", kind: "boolean", optional: false, label: "Signature verified" },
         ],
     },
     {
@@ -1511,6 +1639,81 @@ export const OpMetas = [
             { name: "discoverPubKey", kind: "string", optional: true, label: "Public key" },
         ],
     },
+    {
+        name: "decodeTrace",
+        category: "decode",
+        label: "Decode TRACE packet",
+        tabGroup: "",
+        tabGroupLabel: "",
+        tabGroupSub: "",
+        tabGroupDoc: "",
+        tabLabel: "",
+        packetType: "TRACE",
+        resultTypeName: "TracePayload",
+        params: [
+            {
+                name: "packet",
+                kind: "hex",
+                label: "Full packet hex (SNR bytes are in the path field)",
+                placeholder: "",
+                optional: false,
+                choices: [],
+                showWhen: "",
+                showValue: 0,
+                group: "",
+                action: "",
+                widget: "",
+                autoFill: "packetHex",
+                secret: false,
+            },
+        ],
+        result: [
+            { name: "tag", kind: "number", optional: false, label: "Tag" },
+            { name: "authCode", kind: "number", optional: false, label: "Auth code" },
+            { name: "flags", kind: "number", optional: false, label: "Flags" },
+            { name: "hashWidth", kind: "number", optional: false, label: "Route hash width (bytes)" },
+            { name: "routeHashes", kind: "string[]", optional: false, label: "Route hashes" },
+            { name: "snrs", kind: "string[]", optional: false, label: "SNR values (dB)" },
+            { name: "hopCount", kind: "number", optional: false, label: "Hops with SNR" },
+        ],
+    },
+    {
+        name: "decodeMultipart",
+        category: "decode",
+        label: "Decode MULTIPART",
+        tabGroup: "",
+        tabGroupLabel: "",
+        tabGroupSub: "",
+        tabGroupDoc: "",
+        tabLabel: "",
+        packetType: "MULTIPART",
+        resultTypeName: "MultipartPayload",
+        params: [
+            {
+                name: "payload",
+                kind: "hex",
+                label: "",
+                placeholder: "",
+                optional: false,
+                choices: [],
+                showWhen: "",
+                showValue: 0,
+                group: "",
+                action: "",
+                widget: "",
+                autoFill: "payloadHex",
+                secret: false,
+            },
+        ],
+        result: [
+            { name: "remaining", kind: "number", optional: false, label: "Remaining packets" },
+            { name: "innerType", kind: "string", optional: false, label: "Inner type" },
+            { name: "innerTypeCode", kind: "number", optional: false, label: "Inner type code" },
+            { name: "innerPayloadHex", kind: "string", optional: false, label: "Inner payload (hex)" },
+            { name: "ackCrc", kind: "number", optional: true, label: "ACK CRC32" },
+            { name: "ackCrcHex", kind: "string", optional: true, label: "ACK CRC32 (hex)" },
+        ],
+    },
     {
         name: "generateKeypair",
         category: "key",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshcore-cz/meshpkt",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MeshCore radio packet codec for JavaScript and TypeScript, powered by WebAssembly",
   "type": "module",
   "license": "MIT",