@netkitty/codec 1.0.0

package/dist/headers/DHCPv6.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DHCPv6 = 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");
+/**
+ * DHCPv6 — Dynamic Host Configuration Protocol for IPv6 (RFC 8415). A client/server message is a
+ * 1-byte message-type, a 3-byte transaction-id, then options in a regular code-length-value form:
+ * option-code(2) + option-len(2) + option-data(option-len), no padding. Rides UDP, client port 546 and
+ * server port 547 (over IPv6, multicast ff02::1:2).
+ *
+ * Options are carried generically (code + verbatim hex data) so every option — including ones whose
+ * data is itself nested options (IA_NA/IA_PD) — round-trips byte-for-byte; per-option / nested decoding
+ * is a later enrichment. Relay-agent messages (RELAY-FORW 12 / RELAY-REPL 13) have a DIFFERENT body
+ * (hop-count + 2 IPv6 addresses + options), so their body is kept verbatim (rawBody) rather than
+ * misparsed as a transaction-id, preserving a byte-perfect round-trip.
+ */
+class DHCPv6 extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'dhcpv6';
+        this.name = 'Dynamic Host Configuration Protocol for IPv6';
+        this.nickname = 'DHCPv6';
+        //Client port 546, server port 547 (both UDP, over IPv6). Port-defined (no content signature).
+        this.matchKeys = ['udpport:546', 'udpport:547'];
+        //A leaf header — nothing demuxes above DHCPv6.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    static #RELAY_MESSAGE_TYPES = new Set([12, 13]);
+    get SCHEMA() {
+        return (DHCPv6.#schemaCache ??= DHCPv6.#buildSchema());
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'DHCPv6 type=${msgType} xid=${transactionId}',
+            properties: {
+                //DHCPv6 is message-type-driven (the transaction-id vs relay body shape depends on it), so
+                //the whole message is parsed/emitted here; the fields below carry only schema metadata.
+                msgType: {
+                    type: 'integer',
+                    label: 'Message Type',
+                    minimum: 0,
+                    maximum: 255,
+                    decode: function () {
+                        let available = this.packet.length - this.startPos;
+                        if (available < 1)
+                            return;
+                        //Bound options/body by the UDP payload length, not the whole captured frame, so a
+                        //retained Ethernet FCS or L2 padding after the datagram is not swallowed as bogus
+                        //options — it spills to the raw layer and the packet still round-trips byte-perfect.
+                        if (this.prevCodecModule && this.prevCodecModule.id === 'udp') {
+                            const udpLength = this.prevCodecModule.instance.length.getValue(0);
+                            if (udpLength >= 8 && udpLength - 8 < available)
+                                available = udpLength - 8;
+                        }
+                        const msgType = (0, BufferToNumber_1.BufferToUInt8)(this.readBytes(0, 1));
+                        this.instance.msgType.setValue(msgType);
+                        if (DHCPv6.#RELAY_MESSAGE_TYPES.has(msgType)) {
+                            //Relay-agent message: hop-count(1) + link-address(16) + peer-address(16) +
+                            //options — a different shape, kept verbatim for a byte-perfect round-trip.
+                            if (available > 1)
+                                this.instance.rawBody.setValue((0, BufferToHex_1.BufferToHex)(this.readBytes(1, available - 1)));
+                            else
+                                this.instance.rawBody.setValue('');
+                            return;
+                        }
+                        this.instance.transactionId.setValue((0, BufferToHex_1.BufferToHex)(this.readBytes(1, 3)));
+                        const options = [];
+                        let offset = 4;
+                        //Each option is code(2) len(2) data(len), no terminator. Peek the header (dry-run,
+                        //so it does not extend headerLength), and if the option data would overrun the
+                        //payload, stop and leave the tail to the raw layer — keeping both truncated
+                        //captures and trailing padding byte-perfect. offset advances ≥4 each iteration.
+                        while (offset + 4 <= available) {
+                            const header = this.readBytes(offset, 4, true);
+                            const code = (0, BufferToNumber_1.BufferToUInt16)(header.subarray(0, 2));
+                            const length = (0, BufferToNumber_1.BufferToUInt16)(header.subarray(2, 4));
+                            if (offset + 4 + length > available)
+                                break;
+                            const optionBuffer = this.readBytes(offset, 4 + length);
+                            options.push({ code: code, value: length ? (0, BufferToHex_1.BufferToHex)(optionBuffer.subarray(4)) : '' });
+                            offset += 4 + length;
+                        }
+                        this.instance.options.setValue(options);
+                    },
+                    encode: function () {
+                        const msgType = this.instance.msgType.getValue(0);
+                        this.writeBytes(0, (0, NumberToBuffer_1.UInt8ToBuffer)(msgType));
+                        const rawBody = this.instance.rawBody.getValue('');
+                        //Relay-agent messages (and any message carrying a verbatim body) re-emit rawBody
+                        //as-is — keyed on the message type so a degenerate empty-body relay stays 1 byte.
+                        if (rawBody || DHCPv6.#RELAY_MESSAGE_TYPES.has(msgType)) {
+                            if (rawBody)
+                                this.writeBytes(1, (0, HexToBuffer_1.HexToBuffer)(rawBody));
+                            return;
+                        }
+                        //transaction-id is a fixed 3 bytes — fit any crafted hex to exactly 3 so it never
+                        //shifts the following options (short is left-padded, long is truncated).
+                        this.writeBytes(1, (0, HexToBuffer_1.HexToBuffer)(this.instance.transactionId.getValue('000000'), 3).subarray(0, 3));
+                        let offset = 4;
+                        const options = this.instance.options.getValue([]);
+                        if (options) {
+                            for (const option of options) {
+                                const value = (0, HexToBuffer_1.HexToBuffer)(option.value ? option.value : '');
+                                this.writeBytes(offset, (0, NumberToBuffer_1.UInt16ToBuffer)(option.code ? option.code : 0));
+                                this.writeBytes(offset + 2, (0, NumberToBuffer_1.UInt16ToBuffer)(value.length));
+                                offset += 4;
+                                if (value.length) {
+                                    this.writeBytes(offset, value);
+                                    offset += value.length;
+                                }
+                            }
+                        }
+                    }
+                },
+                transactionId: { type: 'string', label: 'Transaction ID', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX },
+                //Verbatim body for relay-agent messages (RELAY-FORW/RELAY-REPL); empty and hidden for the
+                //common client/server messages, which use transactionId + options.
+                rawBody: { type: 'string', label: 'Relay Body', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX, hidden: true },
+                options: {
+                    type: 'array',
+                    label: 'Options',
+                    items: {
+                        type: 'object',
+                        label: 'Option',
+                        properties: {
+                            code: { type: 'integer', label: 'Option Code', minimum: 0, maximum: 65535 },
+                            value: { type: 'string', label: 'Option Data', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX }
+                        }
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        return !!this.prevCodecModule && this.prevCodecModule.id === 'udp';
+    }
+}
+exports.DHCPv6 = DHCPv6;

package/dist/headers/DNP3.d.ts

@@ -0,0 +1,27 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * DNP3 — Distributed Network Protocol 3 (IEEE 1815), a SCADA protocol common in electric/water
+ * utilities, on TCP/UDP port 20000. Each frame begins with a 10-byte Data Link Layer header: the start
+ * bytes 0x0564, a Length (count of the octets from Control through the user data, excluding CRCs), a
+ * Control octet (DIR / PRM / FCB / FCV(or DFC) / 4-bit Function Code), a little-endian Destination and
+ * Source address, and a header CRC. The user data that follows is carried in blocks of up to 16 octets
+ * each with its own trailing 2-byte CRC.
+ *
+ * This codec decodes the link header structurally and keeps the data-block region (transport header +
+ * application data + the per-block CRCs) verbatim as `payload` hex — de-blocking those CRCs to recover
+ * the transport/application layer is a cross-frame reassembly concern, not a single-packet one. The CRCs
+ * are honored verbatim (never recomputed), so a well-formed frame round-trips byte-for-byte; the frame's
+ * extent is derived from the Length field so a pipelined/trailing frame is left to RawData.
+ */
+export declare class DNP3 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/DNP3.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DNP3 = 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");
+/**
+ * DNP3 — Distributed Network Protocol 3 (IEEE 1815), a SCADA protocol common in electric/water
+ * utilities, on TCP/UDP port 20000. Each frame begins with a 10-byte Data Link Layer header: the start
+ * bytes 0x0564, a Length (count of the octets from Control through the user data, excluding CRCs), a
+ * Control octet (DIR / PRM / FCB / FCV(or DFC) / 4-bit Function Code), a little-endian Destination and
+ * Source address, and a header CRC. The user data that follows is carried in blocks of up to 16 octets
+ * each with its own trailing 2-byte CRC.
+ *
+ * This codec decodes the link header structurally and keeps the data-block region (transport header +
+ * application data + the per-block CRCs) verbatim as `payload` hex — de-blocking those CRCs to recover
+ * the transport/application layer is a cross-frame reassembly concern, not a single-packet one. The CRCs
+ * are honored verbatim (never recomputed), so a well-formed frame round-trips byte-for-byte; the frame's
+ * extent is derived from the Length field so a pipelined/trailing frame is left to RawData.
+ */
+class DNP3 extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'dnp3';
+        this.name = 'Distributed Network Protocol 3';
+        this.nickname = 'DNP3';
+        this.matchKeys = ['tcpport:20000', 'udpport:20000'];
+        //A leaf header — the transport/application layers require de-blocking (a reassembly concern).
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (DNP3.#schemaCache ??= DNP3.#buildSchema());
+    }
+    /** A single bit of the Control octet (byte 3, bit 0 = MSB). */
+    static #flagBit(name, bitOffset, label) {
+        return {
+            type: 'boolean',
+            label: label,
+            decode: function () {
+                this.instance.control[name].setValue(!!this.readBits(3, 1, bitOffset, 1));
+            },
+            encode: function () {
+                const value = !!this.instance.control[name].getValue();
+                this.instance.control[name].setValue(value);
+                this.writeBits(3, 1, bitOffset, 1, value ? 1 : 0);
+            }
+        };
+    }
+    /** The total on-wire frame length derived from the Length field: 10-byte header + data blocks (each
+     * up to 16 data octets plus a 2-byte CRC). */
+    #frameLength() {
+        const length = this.instance.length.getValue(0);
+        const userData = length > 5 ? length - 5 : 0;
+        const blocks = Math.ceil(userData / 16);
+        return 10 + userData + blocks * 2;
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'DNP3 func=${control.functionCode} ${source}->${destination}',
+            properties: {
+                start: this.fieldHex('start', 0, 2, 'Start'),
+                length: this.fieldUInt('length', 2, 1, 'Length'),
+                //Control octet (byte 3, MSB first): DIR / PRM / FCB / FCV(or DFC) / Function Code(4 bits).
+                control: {
+                    type: 'object',
+                    label: 'Control',
+                    properties: {
+                        dir: this.#flagBit('dir', 0, 'Direction'),
+                        prm: this.#flagBit('prm', 1, 'Primary'),
+                        fcb: this.#flagBit('fcb', 2, 'Frame Count Bit'),
+                        fcv: this.#flagBit('fcv', 3, 'Frame Count Valid'),
+                        functionCode: {
+                            type: 'integer',
+                            label: 'Function Code',
+                            minimum: 0,
+                            maximum: 15,
+                            decode: function () { this.instance.control.functionCode.setValue(this.readBits(3, 1, 4, 4)); },
+                            encode: function () { this.writeBits(3, 1, 4, 4, this.instance.control.functionCode.getValue(0)); }
+                        }
+                    }
+                },
+                //Destination and Source are 16-bit little-endian link addresses.
+                destination: {
+                    type: 'integer',
+                    label: 'Destination',
+                    minimum: 0,
+                    maximum: 65535,
+                    decode: function () {
+                        const bytes = this.readBytes(4, 2);
+                        this.instance.destination.setValue(bytes[0] | (bytes[1] << 8));
+                    },
+                    encode: function () {
+                        const value = this.instance.destination.getValue(0);
+                        this.writeBytes(4, Buffer.from([value & 0xff, (value >> 8) & 0xff]));
+                    }
+                },
+                source: {
+                    type: 'integer',
+                    label: 'Source',
+                    minimum: 0,
+                    maximum: 65535,
+                    decode: function () {
+                        const bytes = this.readBytes(6, 2);
+                        this.instance.source.setValue(bytes[0] | (bytes[1] << 8));
+                    },
+                    encode: function () {
+                        const value = this.instance.source.getValue(0);
+                        this.writeBytes(6, Buffer.from([value & 0xff, (value >> 8) & 0xff]));
+                    }
+                },
+                //Header CRC over the preceding 8 octets, honored verbatim (never recomputed).
+                headerCrc: this.fieldHex('headerCrc', 8, 2, 'Header CRC'),
+                //The data-block region: transport header + application data + per-block CRCs, kept verbatim.
+                //Bounded by the Length-derived frame extent so a pipelined/trailing frame is left to raw.
+                payload: {
+                    type: 'string',
+                    label: 'Payload',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const remaining = this.packet.length - this.startPos;
+                        let end = this.#frameLength();
+                        if (end > remaining)
+                            end = remaining;
+                        this.instance.payload.setValue(end > 10 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(10, end - 10)) : '');
+                    },
+                    encode: function () {
+                        const payload = this.instance.payload.getValue('');
+                        if (payload)
+                            this.writeBytes(10, (0, HexToBuffer_1.HexToBuffer)(payload));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //DNP3 rides on TCP/UDP port 20000. Require the 10-byte link header and the 0x0564 start signature.
+        if (!this.prevCodecModule)
+            return false;
+        if (this.prevCodecModule.id !== 'tcp' && this.prevCodecModule.id !== 'udp')
+            return false;
+        if (this.packet.length - this.startPos < 10)
+            return false;
+        const start = this.readBytes(0, 2, true);
+        return start[0] === 0x05 && start[1] === 0x64;
+    }
+}
+exports.DNP3 = DNP3;

package/dist/headers/DNS.d.ts

@@ -0,0 +1,55 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * A domain name. `value` is the resolved dotted string (following any compression pointers) for
+ * display and differential checks; `raw` is the EXACT on-wire bytes of the name at its physical
+ * position (local labels + either a null terminator or a 2-byte compression pointer), which is what
+ * encode re-emits — so a compressed name round-trips byte-for-byte without having to reconstruct the
+ * compression. When crafting a name from scratch (no `raw`), encode falls back to an uncompressed
+ * encoding built from `value`.
+ */
+type DnsName = {
+    value: string;
+    raw: string;
+};
+/**
+ * DNS — Domain Name System (RFC 1035), the message carried over UDP port 53. A 12-byte header (ID,
+ * flags, and the four section counts) followed by the Question, Answer, Authority and Additional
+ * sections. Names use label compression (RFC 1035 §4.1.4): a length octet with its top two bits set
+ * (0xC0) is a 14-bit pointer to an earlier offset in the message.
+ *
+ * Byte-perfect strategy: every name keeps its exact wire bytes (`raw`) and every record's RDATA is
+ * kept as raw hex, so compression pointers — inside names and inside RDATA (CNAME/NS/SOA/MX targets) —
+ * are reproduced verbatim; the resolved dotted name (`value`) is a decoded convenience. Per-RDATA
+ * semantic decoding (A → address, etc.) is a later enrichment on top of this faithful base. DNS over
+ * TCP (which prefixes a 2-byte length and can span segments) is out of scope for this single-packet
+ * codec and belongs to the reassembly layer.
+ */
+export declare class DNS extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    /**
+     * Parse the name at header-relative `offset`. Returns the resolved value + exact physical raw bytes
+     * and the offset just past the physical name. Compression pointers are followed only to build the
+     * resolved value (dry-run reads that never grow headerLength); the physical bytes are the local
+     * labels plus the terminating null OR the 2-byte pointer, so endPos stays exact.
+     */
+    protected readName(offset: number): {
+        name: DnsName;
+        next: number;
+    };
+    /**
+     * Write a name at `offset`. Re-emits the exact `raw` wire bytes when present (byte-perfect for a
+     * decoded name, including its compression pointer); otherwise builds an uncompressed encoding from
+     * the dotted `value` (for names crafted from scratch). Returns the offset past the written name.
+     */
+    protected writeName(offset: number, name: DnsName | undefined): number;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}
+export {};