@hamradio/meshcore 1.1.2 → 1.2.0

package/README.md

@@ -32,14 +32,66 @@ _Packet {
   routeType: 1,
   payloadVersion: 0,
   payloadType: 1,
-  pathHashCount: 1,
-  pathHashSize: 10,
+  pathHashCount: 10,
+  pathHashSize: 1,
   pathHashBytes: 10,
-  pathHashes: [ 'a50e2cb0336db67bbf78' ]
+  pathHashes: [
+    'a5', '0e', '2c',
+    'b0', '33', '6d',
+    'b6', '7b', 'bf',
+    '78'
+  ]
 }
 */
 ```
 
+## Packet structure parsing
+
+The parser can also be instructed to generate a packet structure, useful for debugging or
+printing packet details:
+
+```ts
+import { Packet } from '@hamradio/meshcore';
+
+const raw = new Uint8Array(Buffer.from("050AA50E2CB0336DB67BBF78928A3BB9BF7A8B677C83B6EC0716F9DD10002A06", "hex"));
+const packet = Packet.fromBytes(raw);
+const { structure } = packet.decode(true);
+console.log(structure);
+
+/*
+[
+  {
+    name: 'header',
+    data: Uint8Array(12) [
+        5,  10, 165,  14,  44,
+      176,  51, 109, 182, 123,
+      191, 120
+    ],
+    fields: [
+      { name: 'flags', type: 0, size: 1, bits: [Array] },
+      { name: 'path length', type: 1, size: 1, bits: [Array] },
+      { name: 'path hashes', type: 6, size: 10 }
+    ]
+  },
+  {
+    name: 'response payload',
+    data: Uint8Array(20) [
+      146, 138,  59, 185, 191, 122,
+      139, 103, 124, 131, 182, 236,
+        7,  22, 249, 221,  16,   0,
+       42,   6
+    ],
+    fields: [
+      { name: 'destination hash', type: 1, size: 1, value: 146 },
+      { name: 'source hash', type: 1, size: 1, value: 138 },
+      { name: 'cipher MAC', type: 6, size: 2, value: [Uint8Array] },
+      { name: 'cipher text', type: 6, size: 16, value: [Uint8Array] }
+    ]
+  }
+]
+*/
+```
+
 ## Identities
 
 The package supports:

package/dist/index.d.mts

@@ -1,28 +1,3 @@
-type NodeHash = number;
-interface IIdentity {
-    hash(): NodeHash;
-    toString(): string;
-    verify(signature: Uint8Array, message: Uint8Array): boolean;
-    matches(other: IIdentity | IPublicKey | Uint8Array | string): boolean;
-}
-interface ILocalIdentity extends IIdentity {
-    sign(message: Uint8Array): Uint8Array;
-    calculateSharedSecret(other: IIdentity | IPublicKey): ISharedSecret;
-}
-interface IContact {
-    name: string;
-    identity: IIdentity;
-    calculateSharedSecret(me: ILocalIdentity): ISharedSecret;
-}
-
-type identity_types_IContact = IContact;
-type identity_types_IIdentity = IIdentity;
-type identity_types_ILocalIdentity = ILocalIdentity;
-type identity_types_NodeHash = NodeHash;
-declare namespace identity_types {
-  export type { identity_types_IContact as IContact, identity_types_IIdentity as IIdentity, identity_types_ILocalIdentity as ILocalIdentity, identity_types_NodeHash as NodeHash };
-}
-
 interface IPublicKey {
     toHash(): NodeHash;
     toBytes(): Uint8Array;
@@ -49,53 +24,52 @@ interface IStaticSecret {
     diffieHellman(otherPublicKey: IPublicKey): ISharedSecret;
 }
 
-type crypto_types_IPrivateKey = IPrivateKey;
-type crypto_types_IPublicKey = IPublicKey;
-type crypto_types_ISharedSecret = ISharedSecret;
-type crypto_types_IStaticSecret = IStaticSecret;
-declare namespace crypto_types {
-  export type { crypto_types_IPrivateKey as IPrivateKey, crypto_types_IPublicKey as IPublicKey, crypto_types_ISharedSecret as ISharedSecret, crypto_types_IStaticSecret as IStaticSecret };
-}
-
-declare class PublicKey implements IPublicKey {
-    key: Uint8Array;
-    constructor(key: Uint8Array | string);
-    toHash(): NodeHash;
-    toBytes(): Uint8Array;
+type NodeHash = number;
+interface IIdentity {
+    hash(): NodeHash;
     toString(): string;
-    equals(other: PublicKey | Uint8Array | string): boolean;
-    verify(message: Uint8Array, signature: Uint8Array): boolean;
+    verify(signature: Uint8Array, message: Uint8Array): boolean;
+    matches(other: IIdentity | IPublicKey | Uint8Array | string): boolean;
 }
-declare class PrivateKey {
-    private secretKey;
-    private publicKey;
-    constructor(seed: Uint8Array | string);
-    toPublicKey(): PublicKey;
-    toBytes(): Uint8Array;
-    toString(): string;
+interface ILocalIdentity extends IIdentity {
     sign(message: Uint8Array): Uint8Array;
-    calculateSharedSecret(other: PublicKey | Uint8Array | string): Uint8Array;
-    static generate(): PrivateKey;
+    calculateSharedSecret(other: IIdentity | IPublicKey): ISharedSecret;
 }
-declare class SharedSecret implements ISharedSecret {
-    private secret;
-    constructor(secret: Uint8Array);
-    toHash(): NodeHash;
-    toBytes(): Uint8Array;
-    toString(): string;
-    decrypt(hmac: Uint8Array, ciphertext: Uint8Array): Uint8Array;
-    encrypt(data: Uint8Array): {
-        hmac: Uint8Array;
-        ciphertext: Uint8Array;
-    };
-    private calculateHmac;
-    static fromName(name: string): SharedSecret;
+interface IContact {
+    name: string;
+    identity: IIdentity;
+    calculateSharedSecret(me: ILocalIdentity): ISharedSecret;
 }
-declare class StaticSecret implements IStaticSecret {
-    private secret;
-    constructor(secret: Uint8Array | string);
-    publicKey(): IPublicKey;
-    diffieHellman(otherPublicKey: IPublicKey): SharedSecret;
+
+declare enum FieldType {
+    BITS = 0,
+    UINT8 = 1,
+    UINT16_LE = 2,
+    UINT16_BE = 3,
+    UINT32_LE = 4,
+    UINT32_BE = 5,
+    BYTES = 6,// 8-bits per value
+    WORDS = 7,// 16-bits per value
+    DWORDS = 8,// 32-bits per value
+    QWORDS = 9,// 64-bits per value
+    C_STRING = 10
+}
+type PacketStructure = PacketSegment[];
+interface PacketSegment {
+    name: string;
+    data: Uint8Array;
+    fields: PacketField[];
+}
+interface PacketField {
+    type: FieldType;
+    size: number;
+    name?: string;
+    bits?: PacketFieldBit[];
+    value?: any;
+}
+interface PacketFieldBit {
+    name: string;
+    size: number;
 }
 
 type Uint16 = number;
@@ -105,7 +79,10 @@ interface IPacket {
     pathLength: number;
     path: Uint8Array;
     payload: Uint8Array;
-    decode(): Payload;
+    decode(withStructure?: boolean): Payload | {
+        payload: Payload;
+        structure: PacketStructure;
+    };
 }
 declare enum RouteType {
     TRANSPORT_FLOOD = 0,
@@ -126,12 +103,15 @@ declare enum PayloadType {
     TRACE = 9,
     RAW_CUSTOM = 15
 }
-type Payload = RequestPayload | ResponsePayload | TextPayload | AckPayload | AdvertPayload | GroupTextPayload | GroupDataPayload | AnonReqPayload | PathPayload | TracePayload | RawCustomPayload;
+type Payload = BasePayload & (RequestPayload | ResponsePayload | TextPayload | AckPayload | AdvertPayload | GroupTextPayload | GroupDataPayload | AnonReqPayload | PathPayload | TracePayload | RawCustomPayload);
+interface BasePayload {
+    type: PayloadType;
+}
 interface EncryptedPayload {
     cipherMAC: Uint8Array;
     cipherText: Uint8Array;
 }
-interface RequestPayload {
+interface RequestPayload extends BasePayload {
     type: PayloadType.REQUEST;
     dst: NodeHash;
     src: NodeHash;
@@ -152,7 +132,7 @@ interface DecryptedRequest {
     requestType: RequestType;
     requestData: Uint8Array;
 }
-interface ResponsePayload {
+interface ResponsePayload extends BasePayload {
     type: PayloadType.RESPONSE;
     dst: NodeHash;
     src: NodeHash;
@@ -163,7 +143,7 @@ interface DecryptedResponse {
     timestamp: Date;
     responseData: Uint8Array;
 }
-interface TextPayload {
+interface TextPayload extends BasePayload {
     type: PayloadType.TEXT;
     dst: NodeHash;
     src: NodeHash;
@@ -181,11 +161,11 @@ interface DecryptedText {
     attempt: number;
     message: string;
 }
-interface AckPayload {
+interface AckPayload extends BasePayload {
     type: PayloadType.ACK;
     checksum: Uint8Array;
 }
-interface AdvertPayload {
+interface AdvertPayload extends BasePayload {
     type: PayloadType.ADVERT;
     publicKey: Uint8Array;
     timestamp: Date;
@@ -209,7 +189,7 @@ interface AdvertAppData {
     hasName: boolean;
     name?: string;
 }
-interface GroupTextPayload {
+interface GroupTextPayload extends BasePayload {
     type: PayloadType.GROUP_TEXT;
     channelHash: NodeHash;
     encrypted: EncryptedPayload;
@@ -221,7 +201,7 @@ interface DecryptedGroupText {
     attempt: number;
     message: string;
 }
-interface GroupDataPayload {
+interface GroupDataPayload extends BasePayload {
     type: PayloadType.GROUP_DATA;
     channelHash: NodeHash;
     encrypted: EncryptedPayload;
@@ -231,7 +211,7 @@ interface DecryptedGroupData {
     timestamp: Date;
     data: Uint8Array;
 }
-interface AnonReqPayload {
+interface AnonReqPayload extends BasePayload {
     type: PayloadType.ANON_REQ;
     dst: NodeHash;
     publicKey: Uint8Array;
@@ -242,57 +222,99 @@ interface DecryptedAnonReq {
     timestamp: Date;
     data: Uint8Array;
 }
-interface PathPayload {
+interface PathPayload extends BasePayload {
     type: PayloadType.PATH;
     dst: NodeHash;
     src: NodeHash;
 }
-interface TracePayload {
+interface TracePayload extends BasePayload {
     type: PayloadType.TRACE;
     tag: number;
     authCode: number;
     flags: number;
     nodes: Uint8Array;
 }
-interface RawCustomPayload {
+interface RawCustomPayload extends BasePayload {
     type: PayloadType.RAW_CUSTOM;
     data: Uint8Array;
 }
 
-type packet_types_AckPayload = AckPayload;
-type packet_types_AdvertAppData = AdvertAppData;
-type packet_types_AdvertPayload = AdvertPayload;
-type packet_types_AnonReqPayload = AnonReqPayload;
-type packet_types_DecryptedAnonReq = DecryptedAnonReq;
-type packet_types_DecryptedGroupData = DecryptedGroupData;
-type packet_types_DecryptedGroupText = DecryptedGroupText;
-type packet_types_DecryptedRequest = DecryptedRequest;
-type packet_types_DecryptedResponse = DecryptedResponse;
-type packet_types_DecryptedText = DecryptedText;
-type packet_types_EncryptedPayload = EncryptedPayload;
-type packet_types_GroupDataPayload = GroupDataPayload;
-type packet_types_GroupTextPayload = GroupTextPayload;
-type packet_types_IPacket = IPacket;
-type packet_types_NodeType = NodeType;
-declare const packet_types_NodeType: typeof NodeType;
-type packet_types_PathPayload = PathPayload;
-type packet_types_Payload = Payload;
-type packet_types_PayloadType = PayloadType;
-declare const packet_types_PayloadType: typeof PayloadType;
-type packet_types_RawCustomPayload = RawCustomPayload;
-type packet_types_RequestPayload = RequestPayload;
-type packet_types_RequestType = RequestType;
-declare const packet_types_RequestType: typeof RequestType;
-type packet_types_ResponsePayload = ResponsePayload;
-type packet_types_RouteType = RouteType;
-declare const packet_types_RouteType: typeof RouteType;
-type packet_types_TextPayload = TextPayload;
-type packet_types_TextType = TextType;
-declare const packet_types_TextType: typeof TextType;
-type packet_types_TracePayload = TracePayload;
-type packet_types_Uint16 = Uint16;
-declare namespace packet_types {
-  export { type packet_types_AckPayload as AckPayload, type packet_types_AdvertAppData as AdvertAppData, type packet_types_AdvertPayload as AdvertPayload, type packet_types_AnonReqPayload as AnonReqPayload, type packet_types_DecryptedAnonReq as DecryptedAnonReq, type packet_types_DecryptedGroupData as DecryptedGroupData, type packet_types_DecryptedGroupText as DecryptedGroupText, type packet_types_DecryptedRequest as DecryptedRequest, type packet_types_DecryptedResponse as DecryptedResponse, type packet_types_DecryptedText as DecryptedText, type packet_types_EncryptedPayload as EncryptedPayload, type packet_types_GroupDataPayload as GroupDataPayload, type packet_types_GroupTextPayload as GroupTextPayload, type packet_types_IPacket as IPacket, packet_types_NodeType as NodeType, type packet_types_PathPayload as PathPayload, type packet_types_Payload as Payload, packet_types_PayloadType as PayloadType, type packet_types_RawCustomPayload as RawCustomPayload, type packet_types_RequestPayload as RequestPayload, packet_types_RequestType as RequestType, type packet_types_ResponsePayload as ResponsePayload, packet_types_RouteType as RouteType, type packet_types_TextPayload as TextPayload, packet_types_TextType as TextType, type packet_types_TracePayload as TracePayload, type packet_types_Uint16 as Uint16 };
+declare class Packet implements IPacket {
+    header: number;
+    pathLength: number;
+    path: Uint8Array;
+    payload: Uint8Array;
+    transport?: [number, number];
+    routeType: RouteType;
+    payloadVersion: number;
+    payloadType: PayloadType;
+    pathHashCount: number;
+    pathHashSize: number;
+    pathHashBytes: number;
+    pathHashes: string[];
+    structure?: PacketStructure | undefined;
+    constructor(header: number, transport: [number, number] | undefined, pathLength: number, path: Uint8Array, payload: Uint8Array);
+    static fromBytes(bytes: Uint8Array | string): Packet;
+    static hasTransportCodes(routeType: RouteType): boolean;
+    hash(): string;
+    private ensureStructure;
+    decode(withStructure?: boolean): Payload | {
+        payload: Payload;
+        structure: PacketStructure;
+    };
+    private decodeEncryptedPayload;
+    private decodeRequest;
+    private decodeResponse;
+    private decodeText;
+    private decodeAck;
+    private decodeAdvert;
+    private decodeGroupText;
+    private decodeGroupData;
+    private decodeAnonReq;
+    private decodePath;
+    private decodeTrace;
+    private decodeRawCustom;
+}
+
+declare class PublicKey implements IPublicKey {
+    key: Uint8Array;
+    constructor(key: Uint8Array | string);
+    toHash(): NodeHash;
+    toBytes(): Uint8Array;
+    toString(): string;
+    equals(other: PublicKey | Uint8Array | string): boolean;
+    verify(message: Uint8Array, signature: Uint8Array): boolean;
+}
+declare class PrivateKey {
+    private secretKey;
+    private publicKey;
+    constructor(seed: Uint8Array | string);
+    toPublicKey(): PublicKey;
+    toBytes(): Uint8Array;
+    toString(): string;
+    sign(message: Uint8Array): Uint8Array;
+    calculateSharedSecret(other: PublicKey | Uint8Array | string): Uint8Array;
+    static generate(): PrivateKey;
+}
+declare class SharedSecret implements ISharedSecret {
+    private secret;
+    constructor(secret: Uint8Array);
+    toHash(): NodeHash;
+    toBytes(): Uint8Array;
+    toString(): string;
+    decrypt(hmac: Uint8Array, ciphertext: Uint8Array): Uint8Array;
+    encrypt(data: Uint8Array): {
+        hmac: Uint8Array;
+        ciphertext: Uint8Array;
+    };
+    private calculateHmac;
+    static fromName(name: string): SharedSecret;
+}
+declare class StaticSecret implements IStaticSecret {
+    private secret;
+    constructor(secret: Uint8Array | string);
+    publicKey(): IPublicKey;
+    diffieHellman(otherPublicKey: IPublicKey): SharedSecret;
 }
 
 declare const parseNodeHash: (hash: NodeHash | string | Uint8Array) => NodeHash;
@@ -357,36 +379,4 @@ declare class Contacts {
     };
 }
 
-declare class Packet implements IPacket {
-    header: number;
-    pathLength: number;
-    path: Uint8Array;
-    payload: Uint8Array;
-    transport?: [number, number];
-    routeType: RouteType;
-    payloadVersion: number;
-    payloadType: PayloadType;
-    pathHashCount: number;
-    pathHashSize: number;
-    pathHashBytes: number;
-    pathHashes: string[];
-    constructor(header: number, transport: [number, number] | undefined, pathLength: number, path: Uint8Array, payload: Uint8Array);
-    static fromBytes(bytes: Uint8Array | string): Packet;
-    static hasTransportCodes(routeType: RouteType): boolean;
-    hash(): string;
-    decode(): Payload;
-    private decodeEncryptedPayload;
-    private decodeRequest;
-    private decodeResponse;
-    private decodeText;
-    private decodeAck;
-    private decodeAdvert;
-    private decodeGroupText;
-    private decodeGroupData;
-    private decodeAnonReq;
-    private decodePath;
-    private decodeTrace;
-    private decodeRawCustom;
-}
-
-export { Contact, Contacts, Group, Identity, LocalIdentity, Packet, PrivateKey, PublicKey, SharedSecret, StaticSecret, crypto_types as cryptoTypes, crypto_types as cryptoTypesTypes, identity_types as identityTypes, identity_types as identityTypesTypes, packet_types as packetTypes, packet_types as packetTypesTypes, parseNodeHash };
+export { type AckPayload, type AdvertPayload, type AnonReqPayload, Contact, Contacts, type EncryptedPayload, Group, type GroupDataPayload, type GroupTextPayload, type IContact, type IIdentity, type ILocalIdentity, type IPacket, type IPrivateKey, type IPublicKey, type ISharedSecret, type IStaticSecret, Identity, LocalIdentity, type NodeHash, NodeType, Packet, type PathPayload, type Payload, PayloadType, PrivateKey, PublicKey, type RawCustomPayload, type RequestPayload, RequestType, type ResponsePayload, RouteType, SharedSecret, StaticSecret, type TextPayload, TextType, type TracePayload, parseNodeHash };