@netkitty/codec 1.0.0

package/dist/headers/OPCUA.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPCUA = 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");
+/** The eight OPC UA TCP message types (IEC 62541-6). A valid message begins with one of these. */
+const OPCUA_MESSAGE_TYPES = ['HEL', 'ACK', 'ERR', 'OPN', 'MSG', 'CLO', 'RHE', 'RHF'];
+/** The IsFinal / chunk indicator: F (final), C (intermediate chunk), A (abort). */
+const OPCUA_CHUNK_TYPES = ['F', 'C', 'A'];
+/**
+ * OPC UA Connection Protocol — the OPC UA TCP transport mapping (IEC 62541-6), TCP port 4840. Every OPC
+ * UA TCP message is framed by a fixed 8-byte header: a 3-byte ASCII MessageType (HEL/ACK/ERR/OPN/MSG/
+ * CLO/RHE/RHF), a 1-byte ASCII Chunk/IsFinal indicator (F final, C intermediate chunk, A abort), and a
+ * LITTLE-ENDIAN uint32 MessageSize that counts the WHOLE message including the 8-byte header. The header
+ * is followed by MessageSize − 8 bytes of message body.
+ *
+ * ⚠️ MessageSize is LITTLE-ENDIAN (the only multi-byte field in this header), and there is no
+ * little-endian helper in this codebase, so it is read/written byte-by-byte in its closure. The `| ... <<`
+ * expression yields a signed int32, so `>>> 0` is applied to the whole expression to keep a MessageSize
+ * with the high bit set unsigned. MessageType/Chunk are ASCII text kept as strings.
+ *
+ * The body is message-type-dependent (HEL/ACK carry a protocol version + buffer sizes + endpoint URL;
+ * OPN/MSG/CLO carry a SecureChannelId + security/sequence headers + an encoded body), and much of it is
+ * cross-message / security-context state. So this single-message codec keeps the body verbatim as `body`
+ * hex (byte-perfect), bounded by MessageSize (the body ends at offset MessageSize, clamped to the
+ * captured bytes) so a pipelined/trailing message is left to the codec's recursion / RawData. The
+ * MessageSize is honored when supplied (a crafted message may lie), else derived as 8 + body bytes. A
+ * well-formed message round-trips byte-for-byte. Structuring the per-message-type body is a later slice.
+ */
+class OPCUA extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'opcua';
+        this.name = 'OPC UA Connection Protocol';
+        this.nickname = 'OPC UA';
+        this.matchKeys = ['tcpport:4840'];
+        //A leaf header — the per-message-type body requires message-dependent, cross-message parsing.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (OPCUA.#schemaCache ??= OPCUA.#buildSchema());
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'OPC UA ${messageType}',
+            properties: {
+                //3-byte ASCII message type (HEL/ACK/ERR/OPN/MSG/CLO/RHE/RHF). Kept as a string; encode
+                //writes exactly 3 bytes (a decoded value is always 3 chars; a crafted value is truncated
+                //or zero-padded to 3) so a well-formed message round-trips byte-for-byte.
+                messageType: {
+                    type: 'string',
+                    label: 'Message Type',
+                    minLength: 3,
+                    maxLength: 3,
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.ASCII,
+                    decode: function () {
+                        this.instance.messageType.setValue(this.readBytes(0, 3).toString('latin1'));
+                    },
+                    encode: function () {
+                        const node = this.instance.messageType;
+                        const value = node.getValue('', (nodePath) => this.recordError(nodePath, 'Not Found'));
+                        node.setValue(value);
+                        const buffer = Buffer.alloc(3);
+                        Buffer.from(value, 'latin1').copy(buffer, 0, 0, 3);
+                        this.writeBytes(0, buffer);
+                    }
+                },
+                //1-byte ASCII chunk / IsFinal indicator (F/C/A). Kept as a string; encode writes exactly
+                //1 byte.
+                chunk: {
+                    type: 'string',
+                    label: 'Chunk',
+                    minLength: 1,
+                    maxLength: 1,
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.ASCII,
+                    decode: function () {
+                        this.instance.chunk.setValue(this.readBytes(3, 1).toString('latin1'));
+                    },
+                    encode: function () {
+                        const node = this.instance.chunk;
+                        const value = node.getValue('', (nodePath) => this.recordError(nodePath, 'Not Found'));
+                        node.setValue(value);
+                        const buffer = Buffer.alloc(1);
+                        Buffer.from(value, 'latin1').copy(buffer, 0, 0, 1);
+                        this.writeBytes(3, buffer);
+                    }
+                },
+                //LITTLE-ENDIAN uint32: the total message length INCLUDING the 8-byte header. Honored when
+                //supplied (a crafted message may lie); else derived as 8 + body bytes.
+                messageSize: {
+                    type: 'integer',
+                    label: 'Message Size',
+                    minimum: 0,
+                    maximum: 4294967295,
+                    decode: function () {
+                        const b = this.readBytes(4, 4);
+                        //`|` yields a signed int32, so apply `>>> 0` to the WHOLE expression to get an
+                        //unsigned 32-bit value — otherwise a size with the high bit set decodes negative.
+                        this.instance.messageSize.setValue((b[0] | (b[1] << 8) | (b[2] << 16) | (b[3] << 24)) >>> 0);
+                    },
+                    encode: function () {
+                        const provided = this.instance.messageSize.getValue();
+                        let value = (provided !== undefined && provided !== null)
+                            ? provided
+                            : 8 + (0, HexToBuffer_1.HexToBuffer)(this.instance.body.getValue('')).length;
+                        if (value > 4294967295) {
+                            this.recordError(this.instance.messageSize.getPath(), 'Maximum value is 4294967295');
+                            value = 4294967295;
+                        }
+                        if (value < 0) {
+                            this.recordError(this.instance.messageSize.getPath(), 'Minimum value is 0');
+                            value = 0;
+                        }
+                        this.instance.messageSize.setValue(value);
+                        this.writeBytes(4, Buffer.from([value & 0xff, (value >> 8) & 0xff, (value >> 16) & 0xff, (value >>> 24) & 0xff]));
+                    }
+                },
+                //The message body after the 8-byte header, kept verbatim. Bounded by MessageSize (the body
+                //ends at offset MessageSize) and the captured bytes, so trailing/pipelined data is left to
+                //the codec's recursion / RawData.
+                body: {
+                    type: 'string',
+                    label: 'Body',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const remaining = this.packet.length - this.startPos;
+                        const size = this.instance.messageSize.getValue(0);
+                        let end = size;
+                        if (end < 8)
+                            end = 8;
+                        if (end > remaining)
+                            end = remaining;
+                        this.instance.body.setValue(end > 8 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(8, end - 8)) : '');
+                    },
+                    encode: function () {
+                        const body = this.instance.body.getValue('');
+                        if (body)
+                            this.writeBytes(8, (0, HexToBuffer_1.HexToBuffer)(body));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //OPC UA TCP rides on TCP port 4840. Beyond the port bucket, require the content signature: a
+        //valid 3-char message type plus a valid 1-char chunk indicator — enough to separate OPC UA from
+        //arbitrary port-4840 traffic. No heuristicFallback: 3+1 ASCII chars is a weaker signature than a
+        //magic cookie, so this stays a port-bucket protocol (unlike STUN, whose Magic Cookie is strong
+        //enough for any-port recognition).
+        if (!this.prevCodecModule || this.prevCodecModule.id !== 'tcp')
+            return false;
+        if (this.packet.length - this.startPos < 8)
+            return false;
+        const messageType = this.readBytes(0, 3, true).toString('latin1');
+        if (!OPCUA_MESSAGE_TYPES.includes(messageType))
+            return false;
+        const chunk = this.readBytes(3, 1, true).toString('latin1');
+        return OPCUA_CHUNK_TYPES.includes(chunk);
+    }
+}
+exports.OPCUA = OPCUA;

package/dist/headers/OPCUAPubSub.d.ts

@@ -0,0 +1,33 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * OPC UA PubSub — UADP NetworkMessage (IEC 62541-14 / OPC 10000-14), UDP port 4840. A UADP
+ * NetworkMessage begins with a single UADPFlags octet: the low nibble is the UADPVersion (1 in the
+ * current spec) and the four high bits are enable flags — PublisherId (bit 4, 0x10), GroupHeader
+ * (bit 5, 0x20), PayloadHeader (bit 6, 0x40) and ExtendedFlags1 (bit 7, 0x80). What follows the
+ * UADPFlags octet is entirely conditional on those flags (and on the ExtendedFlags1 / ExtendedFlags2 /
+ * GroupHeader / PayloadHeader sub-flag chains): an optional ExtendedFlags1/2, a variable-length
+ * PublisherId whose width is chosen by ExtendedFlags1 bits 0..2, an optional DataSetClassId GUID, the
+ * GroupHeader, the PayloadHeader, Timestamp/PicoSeconds, promoted fields, the security header and
+ * finally the DataSetMessage payload(s) — all little-endian.
+ *
+ * That layout is too flag-dependent (and cross-message, for chunked/security cases) to slice safely in a
+ * single-message codec, so this header takes the deliberate minimal cut mandated by the design: it
+ * decomposes only the one always-present UADPFlags octet into its version + four enable bits (each bit
+ * of the octet is covered, so it round-trips byte-for-byte), and keeps everything after it verbatim as
+ * `body` hex. The body is bounded by the UDP payload length (so Ethernet padding on a short frame is not
+ * swallowed) and by the captured bytes, leaving any trailing bytes to the codec's recursion / RawData. A
+ * well-formed message round-trips byte-for-byte; per-field UADP dissection (PublisherId, GroupHeader,
+ * DataSetMessages, IEC 62541-14 §7.2) is a later enrichment layered on this faithful base.
+ */
+export declare class OPCUAPubSub 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/OPCUAPubSub.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPCUAPubSub = 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");
+/**
+ * OPC UA PubSub — UADP NetworkMessage (IEC 62541-14 / OPC 10000-14), UDP port 4840. A UADP
+ * NetworkMessage begins with a single UADPFlags octet: the low nibble is the UADPVersion (1 in the
+ * current spec) and the four high bits are enable flags — PublisherId (bit 4, 0x10), GroupHeader
+ * (bit 5, 0x20), PayloadHeader (bit 6, 0x40) and ExtendedFlags1 (bit 7, 0x80). What follows the
+ * UADPFlags octet is entirely conditional on those flags (and on the ExtendedFlags1 / ExtendedFlags2 /
+ * GroupHeader / PayloadHeader sub-flag chains): an optional ExtendedFlags1/2, a variable-length
+ * PublisherId whose width is chosen by ExtendedFlags1 bits 0..2, an optional DataSetClassId GUID, the
+ * GroupHeader, the PayloadHeader, Timestamp/PicoSeconds, promoted fields, the security header and
+ * finally the DataSetMessage payload(s) — all little-endian.
+ *
+ * That layout is too flag-dependent (and cross-message, for chunked/security cases) to slice safely in a
+ * single-message codec, so this header takes the deliberate minimal cut mandated by the design: it
+ * decomposes only the one always-present UADPFlags octet into its version + four enable bits (each bit
+ * of the octet is covered, so it round-trips byte-for-byte), and keeps everything after it verbatim as
+ * `body` hex. The body is bounded by the UDP payload length (so Ethernet padding on a short frame is not
+ * swallowed) and by the captured bytes, leaving any trailing bytes to the codec's recursion / RawData. A
+ * well-formed message round-trips byte-for-byte; per-field UADP dissection (PublisherId, GroupHeader,
+ * DataSetMessages, IEC 62541-14 §7.2) is a later enrichment layered on this faithful base.
+ */
+class OPCUAPubSub extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'opcua-pubsub';
+        this.name = 'OPC UA PubSub';
+        this.nickname = 'OPCUAPubSub';
+        this.matchKeys = ['udpport:4840'];
+        //A leaf header — the flag-conditional UADP body requires cross-field / cross-message parsing.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (OPCUAPubSub.#schemaCache ??= OPCUAPubSub.#buildSchema());
+    }
+    /** A single enable bit of the UADPFlags octet at byte 0 (MSB-first bitOffset; 0/1 value). */
+    static #fieldFlagBit(name, bitOffset, label) {
+        return {
+            type: 'integer',
+            label: label,
+            minimum: 0,
+            maximum: 1,
+            decode: function () {
+                this.instance[name].setValue(this.readBits(0, 1, bitOffset, 1));
+            },
+            encode: function () {
+                const node = this.instance[name];
+                //Line values are clamped in the closure (never rejected by Ajv) so any decoded value
+                //re-encodes; only bit 0 of the supplied value is written into the flag position.
+                let value = node.getValue(0, (nodePath) => this.recordError(nodePath, 'Not Found'));
+                if (value < 0)
+                    value = 0;
+                node.setValue(value & 1);
+                this.writeBits(0, 1, bitOffset, 1, value & 1);
+            }
+        };
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'OPC UA PubSub UADP v${version}',
+            properties: {
+                //UADPFlags low nibble (bits 3..0): the UADPVersion, 1 in the current spec. Kept as a
+                //clamped uint (0..15) so a crafted/other version still round-trips rather than being
+                //rejected on re-encode.
+                version: {
+                    type: 'integer',
+                    label: 'UADP Version',
+                    minimum: 0,
+                    maximum: 15,
+                    decode: function () {
+                        this.instance.version.setValue(this.readBits(0, 1, 4, 4));
+                    },
+                    encode: function () {
+                        let value = this.instance.version.getValue(0, (nodePath) => this.recordError(nodePath, 'Not Found'));
+                        if (value > 15) {
+                            this.recordError(this.instance.version.getPath(), 'Maximum value is 15');
+                            value = 15;
+                        }
+                        if (value < 0)
+                            value = 0;
+                        this.instance.version.setValue(value);
+                        this.writeBits(0, 1, 4, 4, value);
+                    }
+                },
+                //The four UADPFlags enable bits (bits 4..7). Together with the version nibble they cover
+                //all 8 bits of the octet, so the UADPFlags byte is reproduced exactly.
+                publisherIdEnabled: this.#fieldFlagBit('publisherIdEnabled', 3, 'PublisherId Enabled'),
+                groupHeaderEnabled: this.#fieldFlagBit('groupHeaderEnabled', 2, 'GroupHeader Enabled'),
+                payloadHeaderEnabled: this.#fieldFlagBit('payloadHeaderEnabled', 1, 'PayloadHeader Enabled'),
+                extendedFlags1Enabled: this.#fieldFlagBit('extendedFlags1Enabled', 0, 'ExtendedFlags1 Enabled'),
+                //Everything after the UADPFlags octet, kept verbatim. Its layout is fully conditional on
+                //the flag chain and is not sliced here. Bounded by the UDP payload length (so trailing
+                //Ethernet padding on a short frame is not absorbed) and by the captured bytes.
+                body: {
+                    type: 'string',
+                    label: 'Body',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const available = this.#available();
+                        this.instance.body.setValue(available > 1 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(1, available - 1)) : '');
+                    },
+                    encode: function () {
+                        const body = this.instance.body.getValue('');
+                        if (body)
+                            this.writeBytes(1, (0, HexToBuffer_1.HexToBuffer)(body));
+                    }
+                }
+            }
+        };
+    }
+    /**
+     * Bytes of UADP available in this message: the UDP payload (UDP total length minus the 8-byte UDP
+     * header, read from the layer below) clamped to the bytes actually captured. Bounding by the UDP
+     * length keeps a short-frame's Ethernet padding out of the body so the frame round-trips exactly.
+     */
+    #available() {
+        const remaining = this.packet.length - this.startPos;
+        let available = remaining;
+        const prev = this.prevCodecModule;
+        if (prev && prev.id === 'udp') {
+            const udpTotalLength = prev.instance.length.getValue(0);
+            const payload = udpTotalLength - 8;
+            if (payload >= 0 && payload < available)
+                available = payload;
+        }
+        return available;
+    }
+    match() {
+        //OPC UA PubSub UADP rides on UDP port 4840 (opc.tcp binary is the TCP variant and is not this
+        //header). No strong content magic — the UADPFlags octet is only weakly distinctive — so the
+        //well-known UDP port is the signature. Require at least the single always-present UADPFlags octet.
+        if (!this.prevCodecModule || this.prevCodecModule.id !== 'udp')
+            return false;
+        return this.packet.length - this.startPos >= 1;
+    }
+}
+exports.OPCUAPubSub = OPCUAPubSub;

package/dist/headers/OSPF.d.ts

@@ -0,0 +1,31 @@
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * OSPF — Open Shortest Path First (OSPFv2, RFC 2328), carried directly on IP as protocol 89. This codec
+ * decodes the 24-octet common header: an 8-bit Version (`version`, offset 0), an 8-bit Message Type
+ * (`type`, offset 1; 1 Hello, 2 Database Description, 3 LS Request, 4 LS Update, 5 LS Ack), a 16-bit
+ * Packet Length (`packetLength`, offset 2), the Source Router ID (`routerId`, IPv4, offset 4), the Area
+ * ID (`areaId`, IPv4, offset 8), a 16-bit Checksum (`checksum`, offset 12, honored verbatim and never
+ * recomputed so a captured packet round-trips), a 16-bit Auth Type (`auType`, offset 14) and the 8-octet
+ * Authentication field (`auth`, hex, offset 16).
+ *
+ * For a Hello (type 1) the body is decoded field-by-field: Network Mask (offset 24), 16-bit Hello Interval
+ * (offset 28), 8-bit Options (offset 30), 8-bit Router Priority (offset 31), 32-bit Router Dead Interval
+ * (offset 32), Designated and Backup Designated Routers (IPv4, offsets 36 and 40), then the Active
+ * Neighbors list (4-octet Router IDs from offset 44 onward). For all other types the payload is kept
+ * verbatim as `rawBody` hex from offset 24. Both are bounded by min(Packet Length, the bytes the IP layer
+ * below actually made available) and never below the 24-octet header, so a lying length field can't read
+ * past the real IP payload. match() fires on IPv4 protocol 89 or IPv6 Next Header 89 with a full common
+ * header present.
+ */
+export declare class OSPF extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly matchKeys: string[];
+    readonly name: string;
+    readonly nickname: string;
+    readonly demuxProducers: DemuxProducer[];
+    match(): boolean;
+}