@netkitty/codec 1.0.0

package/dist/headers/OpenVPN.d.ts

@@ -0,0 +1,35 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * OpenVPN, the control/data channel protocol on UDP + TCP port 1194. Every packet begins with a single
+ * opcode/key-id octet: the high 5 bits are the opcode (1 P_CONTROL_HARD_RESET_CLIENT_V1, 2 …SERVER_V1,
+ * 3 P_CONTROL_SOFT_RESET_V1, 4 P_ACK_V1, 5 P_CONTROL_V1, 6 P_DATA_V1, 7 …HARD_RESET_CLIENT_V2,
+ * 8 …HARD_RESET_SERVER_V2, 9 P_DATA_V2) and the low 3 bits are the key id. For a control packet the
+ * octet is followed by an 8-byte session id, an optional (config-dependent) HMAC + packet-id when
+ * tls-auth/tls-crypt is used, a message-packet-id array (ACKs) and the message packet-id; a data packet
+ * carries the encrypted/authenticated payload. None of that tail is self-describing without the session's
+ * negotiated crypto parameters.
+ *
+ * Transport framing differs by L4: over UDP the OpenVPN packet is the whole datagram; over TCP a 2-byte
+ * big-endian length prefix precedes each packet (OpenVPN's own record framing on a stream). This header
+ * detects the transport via prevCodecModule.id and structures accordingly — TCP → length prefix then the
+ * packet at offset 2; UDP → the packet directly at offset 0.
+ *
+ * Byte-perfect strategy (minimal slice): structure the opcode + key-id bit split, and keep the remainder
+ * (session id / HMAC / packet-id / ack array for a control packet, or the payload for a data packet)
+ * verbatim as `body` hex, bounded by the transport payload (UDP length − 8, or 2 + the TCP length prefix).
+ * The TCP length prefix is honored when supplied (a crafted frame may lie) else derived from the encoded
+ * packet bytes; a well-formed packet round-trips byte-for-byte. Trailing / pipelined bytes are left to the
+ * codec's recursion / RawData.
+ */
+export declare class OpenVPN 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/OpenVPN.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenVPN = 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");
+/**
+ * OpenVPN, the control/data channel protocol on UDP + TCP port 1194. Every packet begins with a single
+ * opcode/key-id octet: the high 5 bits are the opcode (1 P_CONTROL_HARD_RESET_CLIENT_V1, 2 …SERVER_V1,
+ * 3 P_CONTROL_SOFT_RESET_V1, 4 P_ACK_V1, 5 P_CONTROL_V1, 6 P_DATA_V1, 7 …HARD_RESET_CLIENT_V2,
+ * 8 …HARD_RESET_SERVER_V2, 9 P_DATA_V2) and the low 3 bits are the key id. For a control packet the
+ * octet is followed by an 8-byte session id, an optional (config-dependent) HMAC + packet-id when
+ * tls-auth/tls-crypt is used, a message-packet-id array (ACKs) and the message packet-id; a data packet
+ * carries the encrypted/authenticated payload. None of that tail is self-describing without the session's
+ * negotiated crypto parameters.
+ *
+ * Transport framing differs by L4: over UDP the OpenVPN packet is the whole datagram; over TCP a 2-byte
+ * big-endian length prefix precedes each packet (OpenVPN's own record framing on a stream). This header
+ * detects the transport via prevCodecModule.id and structures accordingly — TCP → length prefix then the
+ * packet at offset 2; UDP → the packet directly at offset 0.
+ *
+ * Byte-perfect strategy (minimal slice): structure the opcode + key-id bit split, and keep the remainder
+ * (session id / HMAC / packet-id / ack array for a control packet, or the payload for a data packet)
+ * verbatim as `body` hex, bounded by the transport payload (UDP length − 8, or 2 + the TCP length prefix).
+ * The TCP length prefix is honored when supplied (a crafted frame may lie) else derived from the encoded
+ * packet bytes; a well-formed packet round-trips byte-for-byte. Trailing / pipelined bytes are left to the
+ * codec's recursion / RawData.
+ */
+class OpenVPN extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'openvpn';
+        this.name = 'OpenVPN Protocol';
+        this.nickname = 'OpenVPN';
+        //OpenVPN's default port 1194 on both UDP and TCP.
+        this.matchKeys = ['udpport:1194', 'tcpport:1194'];
+        //A leaf header — the control/data tail requires the session's negotiated crypto parameters to parse.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (OpenVPN.#schemaCache ??= OpenVPN.#buildSchema());
+    }
+    /** True when this OpenVPN packet rides on TCP (a 2-byte big-endian length prefix precedes the packet). */
+    #isTcp() {
+        return !!this.prevCodecModule && this.prevCodecModule.id === 'tcp';
+    }
+    /** Offset of the OpenVPN packet within this header: 2 bytes past startPos for TCP, 0 for UDP. */
+    #packetOffset() {
+        return this.#isTcp() ? 2 : 0;
+    }
+    /**
+     * Header-relative end offset of the bytes this OpenVPN layer consumes, so a lying length never reads
+     * past the real transport payload and trailing / pipelined data is left to the codec. Over UDP the
+     * bound is (udp.length − 8); over TCP it is 2 (length prefix) + the length carried in that prefix;
+     * both clamped to the captured bytes.
+     */
+    #payloadEnd() {
+        let end = this.packet.length - this.startPos;
+        const prev = this.prevCodecModule;
+        if (prev && prev.id === 'udp') {
+            const udpLength = prev.instance.length.getValue(0);
+            if (udpLength >= 8 && udpLength - 8 < end)
+                end = udpLength - 8;
+        }
+        else if (prev && prev.id === 'tcp') {
+            if (end >= 2) {
+                const prefix = (0, BufferToNumber_1.BufferToUInt16)(this.readBytes(0, 2, true));
+                const total = 2 + prefix;
+                if (total < end)
+                    end = total;
+            }
+        }
+        return end < 0 ? 0 : end;
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'OpenVPN opcode=${opcode} keyId=${keyId}',
+            properties: {
+                //==== TCP-only 2-byte big-endian record length prefix ====
+                //The number of OpenVPN packet bytes that follow this prefix. Absent over UDP.
+                length: {
+                    type: 'integer',
+                    label: 'Length',
+                    minimum: 0,
+                    maximum: 65535,
+                    decode: function () {
+                        if (!this.#isTcp())
+                            return;
+                        this.instance.length.setValue((0, BufferToNumber_1.BufferToUInt16)(this.readBytes(0, 2)));
+                    },
+                    encode: function () {
+                        if (!this.#isTcp())
+                            return;
+                        const provided = this.instance.length.getValue();
+                        if (provided !== undefined && provided !== null) {
+                            //Honored verbatim (a crafted frame may lie about the record length).
+                            let value = provided;
+                            if (value > 65535) {
+                                this.recordError(this.instance.length.getPath(), 'Maximum value is 65535');
+                                value = 65535;
+                            }
+                            if (value < 0) {
+                                this.recordError(this.instance.length.getPath(), 'Minimum value is 0');
+                                value = 0;
+                            }
+                            this.instance.length.setValue(value);
+                            this.writeBytes(0, (0, NumberToBuffer_1.UInt16ToBuffer)(value));
+                        }
+                        else {
+                            //Derive after the packet bytes are written: the prefix counts exactly the
+                            //OpenVPN packet (everything after this 2-byte prefix).
+                            this.writeBytes(0, (0, NumberToBuffer_1.UInt16ToBuffer)(0));
+                            this.addPostSelfEncodeHandler(() => {
+                                const packetLength = this.headerLength - 2;
+                                const value = packetLength > 0 ? (packetLength > 65535 ? 65535 : packetLength) : 0;
+                                this.instance.length.setValue(value);
+                                this.writeBytes(0, (0, NumberToBuffer_1.UInt16ToBuffer)(value));
+                            }, 0);
+                        }
+                    }
+                },
+                //==== opcode/key-id octet ====
+                //High 5 bits: the packet opcode (message type). Any value 0-31 is emitted faithfully.
+                opcode: {
+                    type: 'integer',
+                    label: 'Opcode',
+                    minimum: 0,
+                    maximum: 31,
+                    decode: function () {
+                        this.instance.opcode.setValue(this.readBits(this.#packetOffset(), 1, 0, 5));
+                    },
+                    encode: function () {
+                        const node = this.instance.opcode;
+                        let value = node.getValue(0, (nodePath) => this.recordError(nodePath, 'Not Found'));
+                        if (value > 31) {
+                            this.recordError(node.getPath(), 'Maximum value is 31');
+                            value = 31;
+                        }
+                        if (value < 0) {
+                            this.recordError(node.getPath(), 'Minimum value is 0');
+                            value = 0;
+                        }
+                        node.setValue(value);
+                        this.writeBits(this.#packetOffset(), 1, 0, 5, value);
+                    }
+                },
+                //Low 3 bits: the key id selecting the negotiated crypto key set (0-7).
+                keyId: {
+                    type: 'integer',
+                    label: 'Key ID',
+                    minimum: 0,
+                    maximum: 7,
+                    decode: function () {
+                        this.instance.keyId.setValue(this.readBits(this.#packetOffset(), 1, 5, 3));
+                    },
+                    encode: function () {
+                        const node = this.instance.keyId;
+                        let value = node.getValue(0, (nodePath) => this.recordError(nodePath, 'Not Found'));
+                        if (value > 7) {
+                            this.recordError(node.getPath(), 'Maximum value is 7');
+                            value = 7;
+                        }
+                        if (value < 0) {
+                            this.recordError(node.getPath(), 'Minimum value is 0');
+                            value = 0;
+                        }
+                        node.setValue(value);
+                        this.writeBits(this.#packetOffset(), 1, 5, 3, value);
+                    }
+                },
+                //The remainder kept verbatim: for a control packet the session id + optional HMAC/packet-id
+                //+ ack array + message packet-id; for a data packet the encrypted payload. Bounded by
+                //#payloadEnd so a lying length can't read past the transport payload.
+                body: {
+                    type: 'string',
+                    label: 'Body',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const start = this.#packetOffset() + 1;
+                        const end = this.#payloadEnd();
+                        this.instance.body.setValue(end > start ? (0, BufferToHex_1.BufferToHex)(this.readBytes(start, end - start)) : '');
+                    },
+                    encode: function () {
+                        const start = this.#packetOffset() + 1;
+                        const body = this.instance.body.getValue('');
+                        if (body)
+                            this.writeBytes(start, (0, HexToBuffer_1.HexToBuffer)(body));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //OpenVPN rides UDP/TCP port 1194 (selected via the udpport:1194 / tcpport:1194 buckets). This
+        //stays a port-bucket protocol: matchKeys only, NO heuristicFallback — the opcode/key-id octet is
+        //too weak a signature to claim OpenVPN off port 1194. Over TCP the packet sits after the 2-byte
+        //length prefix; over UDP it is the first byte. Require at least the opcode octet within the
+        //transport payload.
+        if (!this.prevCodecModule)
+            return false;
+        const isTcp = this.prevCodecModule.id === 'tcp';
+        const isUdp = this.prevCodecModule.id === 'udp';
+        if (!isTcp && !isUdp)
+            return false;
+        const offset = isTcp ? 2 : 0;
+        return this.#payloadEnd() >= offset + 1;
+    }
+}
+exports.OpenVPN = OpenVPN;

package/dist/headers/PCWorx.d.ts

@@ -0,0 +1,35 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * PCWorx (Phoenix Contact ILC / AXC classic PLC engineering protocol), TCP port 1962. There is no
+ * public authoritative specification for PCWorx; the on-wire framing used here is reverse-engineered
+ * from the Digital Bond "Redpoint" pcworx-info.nse scanner and the OpenVAS "PCWorx Detection (TCP)"
+ * probe, which agree on a fixed 4-byte message header:
+ *
+ *   offset 0  opcode   (1 byte)  — leading message opcode; 0x01 in every observed PCWorx frame
+ *   offset 1  service  (1 byte)  — service / sequence byte. Requests use small values (Redpoint's
+ *                                  three-step probe sends 0x01, 0x05, 0x06); a response sets the high
+ *                                  bit (the scanner validates a reply by testing this byte == 0x81).
+ *   offset 2  length   (2 bytes, big-endian) — the TOTAL message length in octets INCLUDING this
+ *                                  4-byte header (verified on Redpoint's requests: 0x001a=26 = 4+22,
+ *                                  0x0016=22 = 4+18, 0x000e=14 = 4+10).
+ *
+ * followed by `length - 4` bytes of opcode/service-specific body (session id, string-table indices,
+ * null-terminated PLC-type / firmware / model strings — all cross-message, session-stateful, and not
+ * publicly documented). This single-message codec therefore keeps the body verbatim as `body` hex
+ * (byte-perfect) and does not sub-decode it. The Length is auto-computed (4 + body) on encode when not
+ * supplied, else honored verbatim (a crafted message may lie); the message is bounded by Length so a
+ * pipelined/trailing message is left to the codec's recursion / RawData. A well-formed message
+ * round-trips byte-for-byte.
+ */
+export declare class PCWorx 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/PCWorx.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PCWorx = 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");
+/**
+ * PCWorx (Phoenix Contact ILC / AXC classic PLC engineering protocol), TCP port 1962. There is no
+ * public authoritative specification for PCWorx; the on-wire framing used here is reverse-engineered
+ * from the Digital Bond "Redpoint" pcworx-info.nse scanner and the OpenVAS "PCWorx Detection (TCP)"
+ * probe, which agree on a fixed 4-byte message header:
+ *
+ *   offset 0  opcode   (1 byte)  — leading message opcode; 0x01 in every observed PCWorx frame
+ *   offset 1  service  (1 byte)  — service / sequence byte. Requests use small values (Redpoint's
+ *                                  three-step probe sends 0x01, 0x05, 0x06); a response sets the high
+ *                                  bit (the scanner validates a reply by testing this byte == 0x81).
+ *   offset 2  length   (2 bytes, big-endian) — the TOTAL message length in octets INCLUDING this
+ *                                  4-byte header (verified on Redpoint's requests: 0x001a=26 = 4+22,
+ *                                  0x0016=22 = 4+18, 0x000e=14 = 4+10).
+ *
+ * followed by `length - 4` bytes of opcode/service-specific body (session id, string-table indices,
+ * null-terminated PLC-type / firmware / model strings — all cross-message, session-stateful, and not
+ * publicly documented). This single-message codec therefore keeps the body verbatim as `body` hex
+ * (byte-perfect) and does not sub-decode it. The Length is auto-computed (4 + body) on encode when not
+ * supplied, else honored verbatim (a crafted message may lie); the message is bounded by Length so a
+ * pipelined/trailing message is left to the codec's recursion / RawData. A well-formed message
+ * round-trips byte-for-byte.
+ */
+class PCWorx extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'pcworx';
+        this.name = 'PCWorx';
+        this.nickname = 'PCWorx';
+        this.matchKeys = ['tcpport:1962'];
+        //A leaf header — the body is session-stateful and not publicly specified; kept as hex, not demuxed.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (PCWorx.#schemaCache ??= PCWorx.#buildSchema());
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'PCWorx op=${opcode} svc=${service} len=${length}',
+            properties: {
+                //Leading message opcode (0x01 in every observed PCWorx frame). Kept as a plain uint8
+                //(no enum) so any on-wire value still decodes and re-encodes.
+                opcode: this.fieldUInt('opcode', 0, 1, 'Opcode'),
+                //Service / sequence byte. Requests carry small values; a response sets the high bit
+                //(0x81). Kept as a plain uint8 so both directions round-trip.
+                service: this.fieldUInt('service', 1, 1, 'Service'),
+                length: {
+                    type: 'integer',
+                    label: 'Length',
+                    minimum: 0,
+                    maximum: 65535,
+                    decode: function () {
+                        this.instance.length.setValue((0, BufferToNumber_1.BufferToUInt16)(this.readBytes(2, 2)));
+                    },
+                    encode: function () {
+                        //Length counts the WHOLE message = 4-byte header + body. Honored when supplied
+                        //(a crafted message may lie); else derived from the body.
+                        const provided = this.instance.length.getValue();
+                        let value = (provided !== undefined && provided !== null)
+                            ? provided
+                            : 4 + (0, HexToBuffer_1.HexToBuffer)(this.instance.body.getValue('')).length;
+                        if (value > 65535) {
+                            this.recordError(this.instance.length.getPath(), 'Maximum value is 65535');
+                            value = 65535;
+                        }
+                        this.instance.length.setValue(value);
+                        this.writeBytes(2, (0, NumberToBuffer_1.UInt16ToBuffer)(value));
+                    }
+                },
+                //The opcode/service-specific body after the 4-byte header, kept verbatim. Bounded by the
+                //message Length (the message ends at offset Length) 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 length = this.instance.length.getValue(0);
+                        let end = length;
+                        if (end > remaining)
+                            end = remaining;
+                        this.instance.body.setValue(end > 4 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(4, end - 4)) : '');
+                    },
+                    encode: function () {
+                        const body = this.instance.body.getValue('');
+                        if (body)
+                            this.writeBytes(4, (0, HexToBuffer_1.HexToBuffer)(body));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //PCWorx rides on TCP port 1962. The 4-byte header carries no strong content magic (opcode is
+        //0x01 but that is far too weak to key on off-port), so the well-known port is the signature:
+        //require the full 4-byte header to be present so a too-short segment falls through to raw.
+        //Selection stays port-bucketed (matchKeys) like the other length-bounded TCP payload codecs;
+        //no heuristicFallback.
+        if (!this.prevCodecModule || this.prevCodecModule.id !== 'tcp')
+            return false;
+        return this.packet.length - this.startPos >= 4;
+    }
+}
+exports.PCWorx = PCWorx;

package/dist/headers/PIM.d.ts

@@ -0,0 +1,27 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * PIM — Protocol Independent Multicast, Sparse Mode version 2 (RFC 7761), carried directly over IP as
+ * protocol 103. Every PIM message begins with a fixed 4-byte header: a byte whose high nibble is the
+ * Version (2 for PIMv2) and low nibble is the message Type, a Reserved byte, and a 2-byte Checksum,
+ * followed by the type-specific body.
+ *
+ * Type selects the body layout — 0 Hello, 1 Register, 2 Register-Stop, 3 Join/Prune, 4 Bootstrap,
+ * 5 Assert, 8 Candidate-RP-Advertisement — and several bodies embed Encoded-Address / Encoded-Group /
+ * Encoded-Source structures whose parsing depends on address-family and PIM-neighbour context, so this
+ * single-message codec keeps the body verbatim as `body` hex (byte-perfect) and does not sub-decode it.
+ * The Checksum and Reserved byte are honored verbatim, never recomputed (encode is a faithful executor);
+ * a well-formed PIM message round-trips byte-for-byte. The body is bounded by the enclosing IP payload
+ * so a trailing FCS / pipelined data is left to the codec's recursion / RawData.
+ */
+export declare class PIM 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/PIM.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PIM = 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");
+/**
+ * PIM — Protocol Independent Multicast, Sparse Mode version 2 (RFC 7761), carried directly over IP as
+ * protocol 103. Every PIM message begins with a fixed 4-byte header: a byte whose high nibble is the
+ * Version (2 for PIMv2) and low nibble is the message Type, a Reserved byte, and a 2-byte Checksum,
+ * followed by the type-specific body.
+ *
+ * Type selects the body layout — 0 Hello, 1 Register, 2 Register-Stop, 3 Join/Prune, 4 Bootstrap,
+ * 5 Assert, 8 Candidate-RP-Advertisement — and several bodies embed Encoded-Address / Encoded-Group /
+ * Encoded-Source structures whose parsing depends on address-family and PIM-neighbour context, so this
+ * single-message codec keeps the body verbatim as `body` hex (byte-perfect) and does not sub-decode it.
+ * The Checksum and Reserved byte are honored verbatim, never recomputed (encode is a faithful executor);
+ * a well-formed PIM message round-trips byte-for-byte. The body is bounded by the enclosing IP payload
+ * so a trailing FCS / pipelined data is left to the codec's recursion / RawData.
+ */
+class PIM extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'pim';
+        this.name = 'Protocol Independent Multicast';
+        this.nickname = 'PIM';
+        this.matchKeys = ['ipproto:103'];
+        //A leaf header — the type-specific body (Encoded-Address structures, RP sets, …) needs per-type,
+        //address-family-dependent parsing. Inner recursion is deferred to a later serial slice.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (PIM.#schemaCache ??= PIM.#buildSchema());
+    }
+    /**
+     * Bytes the IP layer below says are available to PIM. IPv4 carries a total-length field, so the PIM
+     * payload is (total length - IP header length); IPv6 carries the payload length directly (plen).
+     * Mirrors the GRE #available() pattern so the body decode is bounded by the real on-wire length
+     * rather than reading to the end of the captured frame (which would swallow Ethernet padding / FCS).
+     * Returns the captured remainder when neither IP length is present.
+     * @private
+     */
+    #available() {
+        let available = this.packet.length - this.startPos;
+        const prev = this.prevCodecModule;
+        if (prev && prev.id === 'ipv4') {
+            const ipPayload = prev.instance.length.getValue(0) - prev.length;
+            if (ipPayload >= 0 && ipPayload < available)
+                available = ipPayload;
+        }
+        else if (prev && prev.id === 'ipv6') {
+            const ipPayload = prev.instance.plen.getValue(0);
+            if (ipPayload >= 0 && ipPayload < available)
+                available = ipPayload;
+        }
+        return available < 0 ? 0 : available;
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'PIM v${version} type=${type}',
+            properties: {
+                //Byte 0: high nibble Version (2 for PIMv2), low nibble Type.
+                version: {
+                    type: 'integer',
+                    label: 'Version',
+                    minimum: 0,
+                    maximum: 15,
+                    decode: function () {
+                        this.instance.version.setValue(this.readBits(0, 1, 0, 4));
+                    },
+                    encode: function () {
+                        const value = this.instance.version.getValue(2);
+                        this.instance.version.setValue(value);
+                        this.writeBits(0, 1, 0, 4, value);
+                    }
+                },
+                type: {
+                    type: 'integer',
+                    label: 'Type',
+                    minimum: 0,
+                    maximum: 15,
+                    decode: function () {
+                        this.instance.type.setValue(this.readBits(0, 1, 4, 4));
+                    },
+                    encode: function () {
+                        const value = this.instance.type.getValue(0);
+                        this.instance.type.setValue(value);
+                        this.writeBits(0, 1, 4, 4, value);
+                    }
+                },
+                //Byte 1: Reserved (0 on transmit for most types, a flags/subtype byte for a few). Kept
+                //verbatim and re-emitted so a non-canonical frame is still byte-perfect.
+                reserved: this.fieldHex('reserved', 1, 1, 'Reserved'),
+                //Bytes 2-3: Checksum (ones-complement over the PIM message). Honored verbatim, never
+                //recomputed, so a captured message round-trips byte-for-byte.
+                checksum: this.fieldUInt('checksum', 2, 2, 'Checksum'),
+                //The type-specific body after the 4-byte header, kept verbatim. Bounded by the enclosing
+                //IP payload (#available) so trailing FCS / pipelined data is left to the codec's recursion.
+                body: {
+                    type: 'string',
+                    label: 'Body',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const end = this.#available();
+                        this.instance.body.setValue(end > 4 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(4, end - 4)) : '');
+                    },
+                    encode: function () {
+                        const body = this.instance.body.getValue('');
+                        if (body)
+                            this.writeBytes(4, (0, HexToBuffer_1.HexToBuffer)(body));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //PIM sits directly above IPv4 (protocol field) or IPv6 (next-header field) with protocol 103,
+        //and needs at least its 4-byte fixed header within the IP payload.
+        if (!this.prevCodecModule)
+            return false;
+        if (this.prevCodecModule.instance.protocol.getValue() !== 103 && this.prevCodecModule.instance.nxt.getValue() !== 103)
+            return false;
+        return this.#available() >= 4;
+    }
+}
+exports.PIM = PIM;

package/dist/headers/POP3.d.ts

@@ -0,0 +1,31 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * POP3 — the Post Office Protocol version 3 (RFC 1939), carried as US-ASCII text over TCP well-known
+ * port 110 (or 995 for the TLS-wrapped POP3S bucket). The control channel is line-based: a client sends
+ * commands (`USER alice\r\n`, `PASS x\r\n`, `RETR 1\r\n`, `QUIT\r\n`, …) and a server sends replies whose
+ * syntax DIFFERS from FTP/SMTP — instead of a 3-digit code, a POP3 reply is a status indicator:
+ * `+OK ...\r\n` (success) or `-ERR ...\r\n` (failure).
+ *
+ * Like FTP, Syslog, SIP and HTTP, the message is text whose full internal structure (arbitrary arguments,
+ * significant whitespace, multi-line RETR/LIST responses) is richer than a form needs. So the ENTIRE raw
+ * message is kept verbatim as the authoritative `message` field (hex) and re-emitted untouched; only the
+ * first line is parsed on decode into display-only metadata (command/argument for a command,
+ * status/replyText for a reply). Encode never reconstructs the message from the parsed fields — it writes
+ * `message` back byte-for-byte — so any conformant (or even malformed) POP3 line round-trips exactly.
+ *
+ * Note: a single TCP segment may carry more than one line or only part of a multi-line response;
+ * reassembly across segments is out of scope. This single-segment codec keeps whatever bytes are present
+ * verbatim, which is byte-perfect for the single-packet case.
+ */
+export declare class POP3 extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}