@netkitty/codec 1.0.0

package/dist/headers/CAPWAP.js

@@ -0,0 +1,275 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPWAP = void 0;
+const BaseHeader_1 = require("../abstracts/BaseHeader");
+const BufferToHex_1 = require("../helper/BufferToHex");
+const HexToBuffer_1 = require("../helper/HexToBuffer");
+const StringContentEncodingEnum_1 = require("../lib/StringContentEncodingEnum");
+/**
+ * CAPWAP — Control And Provisioning of Wireless Access Points (RFC 5415), UDP port 5246 (control) and
+ * 5247 (data). Every CAPWAP message begins with a fixed 8-byte header whose layout is a preamble octet
+ * followed by tightly bit-packed fields:
+ *
+ *   - Preamble (octet 0): Version (high nibble) + Type (low nibble). Type 0 = a CAPWAP header follows,
+ *     Type 1 = the payload is a DTLS record (the header below is then not present).
+ *   - Octets 1-3 (24 bits): HLEN (5 bits, the whole CAPWAP header length in units of 4 octets),
+ *     RID (5 bits, Radio ID), WBID (5 bits, Wireless Binding ID), then the flag bits T, F, L, W, M, K
+ *     (1 bit each) and a 3-bit reserved Flags remainder.
+ *   - Octets 4-5: Fragment ID (16 bits).
+ *   - Octets 6-7: Fragment Offset (13 bits) + a 3-bit reserved field.
+ *
+ * When the M/W flags are set the header carries optional Radio MAC Address / Wireless Specific
+ * Information fields; HLEN delimits the whole header (HLEN × 4 octets), after which the payload begins
+ * (the control-plane Control Header + message elements, or the tunneled 802.3/802.11 data frame).
+ *
+ * This is the minimal, byte-faithful slice: the preamble and every bit-packed field are modelled so an
+ * editor can see/round-trip them, the optional per-flag header fields are kept verbatim as
+ * `headerRemainder` hex (bounded by HLEN × 4), and everything after the header is kept verbatim as
+ * `payload` hex (bounded by the UDP datagram so a retained trailer is not absorbed). Sub-decoding the
+ * Control Header / message elements or the tunneled frame is deferred, so CAPWAP is effectively a leaf.
+ * HLEN is honored verbatim when supplied (a crafted header may lie) else derived from the header bytes;
+ * a well-formed message round-trips byte-for-byte.
+ */
+class CAPWAP extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'capwap';
+        this.name = 'Control And Provisioning of Wireless Access Points';
+        this.nickname = 'CAPWAP';
+        //Well-known UDP ports 5246 (control) and 5247 (data). No content magic, so selection is
+        //port-bucketed only (no heuristicFallback).
+        this.matchKeys = ['udpport:5246', 'udpport:5247'];
+        //A leaf header — the Control Header / message elements and the tunneled frame are kept verbatim.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (CAPWAP.#schemaCache ??= CAPWAP.#buildSchema());
+    }
+    /** The payload length bounded by the UDP datagram (so a retained trailer/padding is not absorbed). */
+    #payloadBound() {
+        let available = this.packet.length - this.startPos;
+        if (this.prevCodecModule && this.prevCodecModule.id === 'udp') {
+            const udpLength = this.prevCodecModule.instance.length.getValue(0);
+            if (udpLength >= 8 && udpLength - 8 < available)
+                available = udpLength - 8;
+        }
+        return available < 0 ? 0 : available;
+    }
+    /** A single flag bit within the 24-bit field packed across octets 1-3 (bit 0 = MSB of octet 1). */
+    static #flagBit(name, bitOffset, label) {
+        return {
+            type: 'boolean',
+            label: label,
+            decode: function () {
+                this.instance.flags[name].setValue(!!this.readBits(1, 3, bitOffset, 1));
+            },
+            encode: function () {
+                const value = !!this.instance.flags[name].getValue();
+                this.instance.flags[name].setValue(value);
+                this.writeBits(1, 3, bitOffset, 1, value ? 1 : 0);
+            }
+        };
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'CAPWAP v${version} type=${type} hlen=${hlen}',
+            properties: {
+                //Preamble (octet 0): Version (high nibble) + Type (low nibble, 0 = CAPWAP header, 1 = DTLS).
+                version: {
+                    type: 'integer',
+                    label: 'Version',
+                    minimum: 0,
+                    maximum: 15,
+                    decode: function () {
+                        this.instance.version.setValue(this.readBits(0, 1, 0, 4));
+                    },
+                    encode: function () {
+                        this.writeBits(0, 1, 0, 4, this.instance.version.getValue(0));
+                    }
+                },
+                type: {
+                    type: 'integer',
+                    label: 'Type',
+                    minimum: 0,
+                    maximum: 15,
+                    decode: function () {
+                        this.instance.type.setValue(this.readBits(0, 1, 4, 4));
+                    },
+                    encode: function () {
+                        this.writeBits(0, 1, 4, 4, this.instance.type.getValue(0));
+                    }
+                },
+                //HLEN (octet 1-3 bits 0-4): the whole CAPWAP header length in units of 4 octets. Honored
+                //verbatim when supplied (a crafted header may lie); else derived from the 8-byte fixed
+                //header plus the verbatim optional (headerRemainder) bytes. HLEN × 4 delimits the header.
+                hlen: {
+                    type: 'integer',
+                    label: 'HLEN',
+                    minimum: 0,
+                    maximum: 31,
+                    decode: function () {
+                        this.instance.hlen.setValue(this.readBits(1, 3, 0, 5));
+                    },
+                    encode: function () {
+                        const provided = this.instance.hlen.getValue();
+                        let value = (provided !== undefined && provided !== null)
+                            ? provided
+                            : Math.ceil((8 + (0, HexToBuffer_1.HexToBuffer)(this.instance.headerRemainder.getValue('')).length) / 4);
+                        if (value > 31) {
+                            this.recordError(this.instance.hlen.getPath(), 'Maximum value is 31');
+                            value = 31;
+                        }
+                        if (value < 0) {
+                            this.recordError(this.instance.hlen.getPath(), 'Minimum value is 0');
+                            value = 0;
+                        }
+                        this.instance.hlen.setValue(value);
+                        this.writeBits(1, 3, 0, 5, value);
+                    }
+                },
+                //RID (octet 1-3 bits 5-9): Radio ID.
+                rid: {
+                    type: 'integer',
+                    label: 'RID',
+                    minimum: 0,
+                    maximum: 31,
+                    decode: function () {
+                        this.instance.rid.setValue(this.readBits(1, 3, 5, 5));
+                    },
+                    encode: function () {
+                        this.writeBits(1, 3, 5, 5, this.instance.rid.getValue(0));
+                    }
+                },
+                //WBID (octet 1-3 bits 10-14): Wireless Binding ID (1 = IEEE 802.11).
+                wbid: {
+                    type: 'integer',
+                    label: 'WBID',
+                    minimum: 0,
+                    maximum: 31,
+                    decode: function () {
+                        this.instance.wbid.setValue(this.readBits(1, 3, 10, 5));
+                    },
+                    encode: function () {
+                        this.writeBits(1, 3, 10, 5, this.instance.wbid.getValue(0));
+                    }
+                },
+                //Flag bits (octet 1-3 bits 15-20): T (payload type), F (fragment), L (last fragment),
+                //W (Wireless Specific Info present), M (Radio MAC present), K (keep-alive).
+                flags: {
+                    type: 'object',
+                    label: 'Flags',
+                    properties: {
+                        t: this.#flagBit('t', 15, 'T (Payload Type)'),
+                        f: this.#flagBit('f', 16, 'F (Fragment)'),
+                        l: this.#flagBit('l', 17, 'L (Last Fragment)'),
+                        w: this.#flagBit('w', 18, 'W (Wireless Specific Info)'),
+                        m: this.#flagBit('m', 19, 'M (Radio MAC Present)'),
+                        k: this.#flagBit('k', 20, 'K (Keep-Alive)')
+                    }
+                },
+                //Flags reserved remainder (octet 1-3 bits 21-23). RFC 5415 requires 0, kept verbatim.
+                flagsReserved: {
+                    type: 'integer',
+                    label: 'Flags Reserved',
+                    minimum: 0,
+                    maximum: 7,
+                    hidden: true,
+                    decode: function () {
+                        this.instance.flagsReserved.setValue(this.readBits(1, 3, 21, 3));
+                    },
+                    encode: function () {
+                        this.writeBits(1, 3, 21, 3, this.instance.flagsReserved.getValue(0));
+                    }
+                },
+                //Fragment ID (octet 4-5): identifies fragments of a single CAPWAP message.
+                fragmentId: this.fieldUInt('fragmentId', 4, 2, 'Fragment ID'),
+                //Fragment Offset (octet 6-7 bits 0-12): the fragment's offset in units of 8 octets.
+                fragmentOffset: {
+                    type: 'integer',
+                    label: 'Fragment Offset',
+                    minimum: 0,
+                    maximum: 8191,
+                    decode: function () {
+                        this.instance.fragmentOffset.setValue(this.readBits(6, 2, 0, 13));
+                    },
+                    encode: function () {
+                        this.writeBits(6, 2, 0, 13, this.instance.fragmentOffset.getValue(0));
+                    }
+                },
+                //Reserved (octet 6-7 bits 13-15). RFC 5415 requires 0, kept verbatim.
+                reserved: {
+                    type: 'integer',
+                    label: 'Reserved',
+                    minimum: 0,
+                    maximum: 7,
+                    hidden: true,
+                    decode: function () {
+                        this.instance.reserved.setValue(this.readBits(6, 2, 13, 3));
+                    },
+                    encode: function () {
+                        this.writeBits(6, 2, 13, 3, this.instance.reserved.getValue(0));
+                    }
+                },
+                //The optional per-flag header fields (Radio MAC Address / Wireless Specific Information),
+                //kept verbatim and bounded by HLEN × 4. Empty for the minimal 8-byte header (HLEN = 2).
+                headerRemainder: {
+                    type: 'string',
+                    label: 'Header Remainder',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const hlen = this.instance.hlen.getValue(0);
+                        const available = this.packet.length - this.startPos;
+                        let headerEnd = hlen * 4;
+                        if (headerEnd < 8)
+                            headerEnd = 8;
+                        if (headerEnd > available)
+                            headerEnd = available;
+                        this.instance.headerRemainder.setValue(headerEnd > 8 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(8, headerEnd - 8)) : '');
+                    },
+                    encode: function () {
+                        const headerRemainder = this.instance.headerRemainder.getValue('');
+                        if (headerRemainder)
+                            this.writeBytes(8, (0, HexToBuffer_1.HexToBuffer)(headerRemainder));
+                    }
+                },
+                //Everything after the CAPWAP header (Control Header + message elements, or the tunneled
+                //802.3/802.11 data frame), kept verbatim. Bounded by the UDP datagram so a retained
+                //trailer is not absorbed; sub-decoding is deferred (CAPWAP is effectively a leaf here).
+                payload: {
+                    type: 'string',
+                    label: 'Payload',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const hlen = this.instance.hlen.getValue(0);
+                        let headerEnd = hlen * 4;
+                        if (headerEnd < 8)
+                            headerEnd = 8;
+                        const end = this.#payloadBound();
+                        if (headerEnd > end)
+                            headerEnd = end;
+                        this.instance.payload.setValue(end > headerEnd ? (0, BufferToHex_1.BufferToHex)(this.readBytes(headerEnd, end - headerEnd)) : '');
+                    },
+                    encode: function () {
+                        const hlen = this.instance.hlen.getValue(0);
+                        let headerEnd = hlen * 4;
+                        if (headerEnd < 8)
+                            headerEnd = 8;
+                        const payload = this.instance.payload.getValue('');
+                        if (payload)
+                            this.writeBytes(headerEnd, (0, HexToBuffer_1.HexToBuffer)(payload));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //Require the fixed 8-byte header within the UDP payload (not just the captured frame — a padded
+        //sub-8-byte datagram on a CAPWAP port would otherwise over-read the trailer into the header).
+        if (!this.prevCodecModule || this.prevCodecModule.id !== 'udp')
+            return false;
+        return this.#payloadBound() >= 8;
+    }
+}
+exports.CAPWAP = CAPWAP;

package/dist/headers/CDP.d.ts

@@ -0,0 +1,25 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * CDP — Cisco Discovery Protocol, carried in an 802.3 frame over LLC/SNAP with OUI 0x00000C and PID
+ * 0x2000. A 4-byte header — Version (1), Time-to-Live (1) and a 2-byte Checksum — is followed by a
+ * sequence of TLVs, each a 2-byte Type + 2-byte Length (the whole TLV octet count including this 4-byte
+ * TLV header) + value. Common types: 0x0001 Device ID, 0x0002 Addresses, 0x0003 Port ID, 0x0004
+ * Capabilities, 0x0005 Software Version, 0x0006 Platform.
+ *
+ * The TLV values are kept verbatim as hex (device names, address lists and capability bitmaps need no
+ * form structure), the Checksum is honored verbatim (never recomputed), and the TLV walk is bounded by
+ * the captured bytes so a corrupt Length can't run past the frame. A well-formed CDP frame round-trips
+ * byte-for-byte.
+ */
+export declare class CDP extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}

package/dist/headers/CDP.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CDP = void 0;
+const BaseHeader_1 = require("../abstracts/BaseHeader");
+const BufferToHex_1 = require("../helper/BufferToHex");
+const HexToBuffer_1 = require("../helper/HexToBuffer");
+const BufferToNumber_1 = require("../helper/BufferToNumber");
+const NumberToBuffer_1 = require("../helper/NumberToBuffer");
+const StringContentEncodingEnum_1 = require("../lib/StringContentEncodingEnum");
+/**
+ * CDP — Cisco Discovery Protocol, carried in an 802.3 frame over LLC/SNAP with OUI 0x00000C and PID
+ * 0x2000. A 4-byte header — Version (1), Time-to-Live (1) and a 2-byte Checksum — is followed by a
+ * sequence of TLVs, each a 2-byte Type + 2-byte Length (the whole TLV octet count including this 4-byte
+ * TLV header) + value. Common types: 0x0001 Device ID, 0x0002 Addresses, 0x0003 Port ID, 0x0004
+ * Capabilities, 0x0005 Software Version, 0x0006 Platform.
+ *
+ * The TLV values are kept verbatim as hex (device names, address lists and capability bitmaps need no
+ * form structure), the Checksum is honored verbatim (never recomputed), and the TLV walk is bounded by
+ * the captured bytes so a corrupt Length can't run past the frame. A well-formed CDP frame round-trips
+ * byte-for-byte.
+ */
+class CDP extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'cdp';
+        this.name = 'Cisco Discovery Protocol';
+        this.nickname = 'CDP';
+        this.matchKeys = ['snapoui:00000c2000'];
+        //A leaf — CDP TLVs carry no encapsulated protocol.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (CDP.#schemaCache ??= CDP.#buildSchema());
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'CDP v${version} ttl=${ttl}',
+            properties: {
+                version: this.fieldUInt('version', 0, 1, 'Version'),
+                ttl: this.fieldUInt('ttl', 1, 1, 'TTL'),
+                //Honored verbatim — the ones-complement checksum is never recomputed, so a captured frame
+                //round-trips byte-for-byte.
+                checksum: this.fieldHex('checksum', 2, 2, 'Checksum'),
+                tlvs: {
+                    type: 'array',
+                    label: 'TLVs',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            type: { type: 'integer', label: 'Type', minimum: 0, maximum: 65535 },
+                            length: { type: 'integer', label: 'Length', minimum: 0, maximum: 65535 },
+                            value: { type: 'string', label: 'Value', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX }
+                        }
+                    },
+                    decode: function () {
+                        const available = this.packet.length - this.startPos;
+                        const tlvs = [];
+                        let offset = 4;
+                        while (offset + 4 <= available) {
+                            const type = (0, BufferToNumber_1.BufferToUInt16)(this.readBytes(offset, 2, true));
+                            const length = (0, BufferToNumber_1.BufferToUInt16)(this.readBytes(offset + 2, 2, true));
+                            //A Length below the 4-byte TLV header is malformed — record and stop.
+                            if (length < 4) {
+                                this.recordError(this.instance.tlvs.getPath(), `Invalid TLV length ${length}`);
+                                break;
+                            }
+                            let end = offset + length;
+                            if (end > available)
+                                end = available;
+                            const value = end > offset + 4 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(offset + 4, end - (offset + 4))) : '';
+                            tlvs.push({ type: type, length: length, value: value });
+                            offset += length;
+                        }
+                        //Mark the whole consumed TLV region so an empty-value trailing TLV is not re-decoded
+                        //as trailing RawData and duplicated on encode (the headers above are dryRun peeks).
+                        const consumedEnd = offset < available ? offset : available;
+                        if (consumedEnd > 4)
+                            this.readBytes(4, consumedEnd - 4);
+                        this.instance.tlvs.setValue(tlvs);
+                    },
+                    encode: function () {
+                        const tlvs = this.instance.tlvs.getValue();
+                        if (!Array.isArray(tlvs))
+                            return;
+                        let offset = 4;
+                        for (const tlv of tlvs) {
+                            const valueBuffer = (0, HexToBuffer_1.HexToBuffer)(tlv && tlv.value ? String(tlv.value) : '');
+                            const providedLength = Number(tlv && tlv.length);
+                            const lengthValue = (Number.isFinite(providedLength) && providedLength > 0)
+                                ? providedLength
+                                : 4 + valueBuffer.length;
+                            const type = Number(tlv && tlv.type) || 0;
+                            this.writeBytes(offset, (0, NumberToBuffer_1.UInt16ToBuffer)(type & 0xffff));
+                            this.writeBytes(offset + 2, (0, NumberToBuffer_1.UInt16ToBuffer)(lengthValue > 65535 ? 65535 : lengthValue));
+                            if (valueBuffer.length)
+                                this.writeBytes(offset + 4, valueBuffer);
+                            offset += 4 + valueBuffer.length;
+                        }
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //A SNAP child under Cisco OUI 0x00000C + PID 0x2000. Re-verify the OUI/PID off the SNAP parent
+        //rather than trusting the key alone, and require the 4-byte CDP header.
+        const prev = this.prevCodecModule;
+        if (!prev || prev.id !== 'snap')
+            return false;
+        if (prev.instance.oui.getValue('') !== '00000c' || prev.instance.etherType.getValue('') !== '2000')
+            return false;
+        return this.packet.length - this.startPos >= 4;
+    }
+}
+exports.CDP = CDP;

package/dist/headers/CMS.d.ts

@@ -0,0 +1,33 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * CMS — China smart-substation communication (DL/T 2811-2024, "变电站二次系统通信报文规范"), the
+ * State-Grid replacement for IEC 61850 MMS that maps ACSI directly onto TCP (port 8102), dropping the
+ * OSI upper layers. Per DL/T 2811 §6.1, an Application Protocol Data Unit (APDU) is an Application
+ * Protocol Control Header (APCH) followed by an Application Service Data Unit (ASDU):
+ *
+ *   APCH (4 bytes): Control Code CC — Next(bit8) + Resp(bit7) + Err(bit6) + bak(bit5) + a 4-bit Protocol
+ *                   type PI (low nibble, = 0x01); Service Code SC (1 byte, §6.1.2 Table 1: 1 Associate,
+ *                   2 Abort, 3 Release, 48 GetDataValues, 83 GetAllDataValues, 154 AssociateNegotiate,
+ *                   155 GetAllDataDefinition, …); Frame Length FL (2 bytes, little-endian, the APDU
+ *                   length excluding the APCH).
+ *   ASDU (FL bytes): Service Request Id ReqID (2 bytes, little-endian, §6.2 — 1..65535, 0 for Report)
+ *                    + the service data area (encoded per the SC, kept verbatim here).
+ *
+ * An empty frame (§6.3) has FL=0 (APCH only) or FL=2 (APCH+ReqID). A large ASDU is framed (§6.5) with
+ * the Next bit set. A CMS PDU can also exceed one TCP segment; this single-packet stateless codec
+ * structures the APCH + the ASDU bytes present in the packet, leaving TCP-stream reassembly to a higher
+ * layer (mid-PDU continuation segments carry no APCH — their first byte's low nibble is not the PI 0x01
+ * — so they fall to raw). A single frame round-trips byte-for-byte.
+ */
+export declare class CMS extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}