@netkitty/codec 1.0.0

package/dist/headers/STOMP.js

@@ -0,0 +1,177 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOMP = 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");
+/** STOMP frame commands (STOMP 1.2) used only to recognize a frame's start-line. */
+const STOMP_COMMANDS = ['CONNECT', 'STOMP', 'CONNECTED', 'SEND', 'SUBSCRIBE', 'UNSUBSCRIBE', 'ACK', 'NACK', 'BEGIN', 'COMMIT', 'ABORT', 'DISCONNECT', 'MESSAGE', 'RECEIPT', 'ERROR'];
+/**
+ * STOMP — the Simple (or Streaming) Text Oriented Messaging Protocol (STOMP 1.2), a text framing for
+ * message brokers, carried over TCP (well-known port 61613, the ActiveMQ default). A STOMP frame is
+ * US-ASCII text: a COMMAND line, then zero or more `header:value` lines, a blank line, an optional body,
+ * and a terminating NUL (0x00):
+ *
+ *   COMMAND{EOL}
+ *   header1:value1{EOL}
+ *   header2:value2{EOL}
+ *   {EOL}
+ *   body^@
+ *
+ * where {EOL} is a line feed (STOMP 1.2 also permits CR LF) and ^@ is the NUL octet. Between frames a
+ * client/server may send a bare {EOL} as a heartbeat.
+ *
+ * Like SIP/Ident/HTTP (the verbatim-message pattern): a frame is free-form text — arbitrary header
+ * ordering, header-value escaping (\c \n \r \\), and a body of any content-type whose length may be an
+ * explicit `content-length` header or run to the NUL — so the exact bytes a peer sees are richer than a
+ * form needs and whitespace/ordering is significant. The ENTIRE raw payload is therefore the single
+ * source of truth: decoded verbatim to hex in the authoritative `message` field and re-emitted
+ * byte-for-byte on encode. On top of that the frame's COMMAND line and a few common display headers
+ * (destination, content-type, content-length) are parsed into DISPLAY-ONLY metadata; those carry no
+ * codec of their own and never reconstruct the bytes — the message owns them. So any STOMP frame
+ * round-trips exactly.
+ *
+ * Framing: STOMP frames are NUL-terminated and several may be pipelined in one TCP segment, but — like
+ * the other text verbatim leaves (SIP/HTTP/Ident) and because TCP carries no per-message length here —
+ * this terminal layer consumes to the end of the segment and keeps it as one verbatim `message`. A
+ * well-formed single-frame segment round-trips byte-for-byte.
+ *
+ * Matching rationale (NO heuristicFallback): STOMP is claimed ONLY on the tcp:61613 bucket, and only
+ * when the first line is a known STOMP command — a defensive content gate (like SIP's start-line) so
+ * non-STOMP traffic on 61613 falls losslessly to raw. Joining the global content-heuristic chain would
+ * risk mislabeling arbitrary text TCP payloads on any port, so selection stays port-bucketed.
+ */
+class STOMP extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'stomp';
+        this.name = 'Simple Text Oriented Messaging Protocol';
+        this.nickname = 'STOMP';
+        //STOMP is recognized ONLY on the well-known port 61613 — deliberately NOT via heuristicFallback. A
+        //STOMP frame is US-ASCII text; joining the global heuristic chain would mislabel arbitrary text TCP
+        //payloads on any port. Confining STOMP to tcp:61613 + a command-line gate keeps that impossible;
+        //alt-port STOMP is rare and falls losslessly to raw. See the class doc for the full rationale.
+        this.matchKeys = ['tcpport:61613'];
+        //A leaf header — a STOMP frame's body is an opaque message payload; nothing demuxes off it.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (_a.#schemaCache ??= _a.#buildSchema());
+    }
+    /** Bytes available to this header: STOMP rides on TCP, which has no per-message length. */
+    #payloadLength() {
+        const available = this.packet.length - this.startPos;
+        return available < 0 ? 0 : available;
+    }
+    /** The first line of the payload (up to the first LF, CR stripped), or the whole payload if none. */
+    static #firstLine(text) {
+        const lf = text.indexOf('\n');
+        let line = lf >= 0 ? text.slice(0, lf) : text;
+        if (line.endsWith('\r'))
+            line = line.slice(0, -1);
+        return line;
+    }
+    /**
+     * Parse the COMMAND line and a few common headers into the display-only metadata fields. The frame
+     * is `COMMAND{EOL}(header:value{EOL})*{EOL}body`. Populated on decode only — these fields have no
+     * encode, so they never affect the re-emitted bytes and never mutate `message`. Never throws:
+     * missing tokens yield empty strings / 0.
+     */
+    #parse(text) {
+        const command = _a.#firstLine(text);
+        this.instance.command.setValue(command);
+        //Walk the header lines (COMMAND line already consumed) up to the blank line that ends the
+        //headers; pull the common display headers. Header names are case-sensitive in STOMP 1.2.
+        let destination = '';
+        let contentType = '';
+        let contentLength = 0;
+        const lines = text.split('\n');
+        for (let i = 1; i < lines.length; i++) {
+            let line = lines[i];
+            if (line.endsWith('\r'))
+                line = line.slice(0, -1);
+            if (line === '')
+                break;
+            const colon = line.indexOf(':');
+            if (colon < 0)
+                continue;
+            const key = line.slice(0, colon);
+            const value = line.slice(colon + 1);
+            if (key === 'destination' && destination === '')
+                destination = value;
+            else if (key === 'content-type' && contentType === '')
+                contentType = value;
+            else if (key === 'content-length' && contentLength === 0) {
+                const parsed = parseInt(value.trim(), 10);
+                if (Number.isFinite(parsed) && parsed > 0)
+                    contentLength = parsed;
+            }
+        }
+        this.instance.destination.setValue(destination);
+        this.instance.contentType.setValue(contentType);
+        this.instance.contentLength.setValue(contentLength);
+        this.instance.summaryInfo.setValue(destination ? `${command} ${destination}` : command);
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'STOMP ${summaryInfo}',
+            properties: {
+                //Display-only metadata parsed from the frame on decode (no encode — populated by the
+                //`message` field below, never read back). command is the frame's COMMAND line;
+                //destination/content-type/content-length are the common headers, present when the frame
+                //carries them.
+                command: { type: 'string', label: 'Command', default: '' },
+                destination: { type: 'string', label: 'Destination', default: '' },
+                contentType: { type: 'string', label: 'Content Type', default: '' },
+                contentLength: { type: 'integer', label: 'Content Length', minimum: 0, default: 0 },
+                //Drives the one-line summary (COMMAND + destination when present).
+                summaryInfo: { type: 'string', label: 'Summary', hidden: true, default: '' },
+                //The whole raw payload is the single source of truth: decoded verbatim to hex and
+                //re-emitted untouched (byte-perfect for any STOMP frame). The COMMAND line and common
+                //headers are parsed into the display-only metadata above, which carry no codec of their own.
+                message: {
+                    type: 'string',
+                    label: 'Message',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    default: '',
+                    decode: function () {
+                        const available = this.#payloadLength();
+                        if (available <= 0) {
+                            this.instance.message.setValue('');
+                            this.#parse('');
+                            return;
+                        }
+                        const raw = this.readBytes(0, available);
+                        this.instance.message.setValue((0, BufferToHex_1.BufferToHex)(raw));
+                        this.#parse(raw.toString('latin1'));
+                    },
+                    encode: function () {
+                        //Re-emit the authoritative payload verbatim — never reconstruct from metadata.
+                        this.writeBytes(0, (0, HexToBuffer_1.HexToBuffer)(this.instance.message.getValue('')));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //Reached only on the tcp:61613 bucket. Recognize STOMP by its start-line signature: the first
+        //line (up to the first LF) is a known STOMP command — so non-STOMP traffic on 61613 (and bare
+        //heartbeat newlines) falls through to raw rather than claiming an un-decodable text layer.
+        if (!this.prevCodecModule)
+            return false;
+        if (this.prevCodecModule.id !== 'tcp')
+            return false;
+        if (this.#payloadLength() <= 0)
+            return false;
+        //Read a small lead window (long enough for the longest command + terminator) without advancing.
+        const lead = this.readBytes(0, 16, true).toString('latin1');
+        const line = _a.#firstLine(lead);
+        return STOMP_COMMANDS.includes(line);
+    }
+}
+exports.STOMP = STOMP;
+_a = STOMP;

package/dist/headers/STP.d.ts

@@ -0,0 +1,26 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * STP — Spanning Tree Protocol BPDU (IEEE 802.1D, and RSTP/MSTP 802.1w/s), carried in an 802.3 frame
+ * over LLC with DSAP/SSAP 0x42. Every BPDU opens with a 4-byte fixed part: a 2-byte Protocol Identifier
+ * (0x0000), a 1-byte Protocol Version (0 STP, 2 RSTP, 3 MSTP) and a 1-byte BPDU Type (0x00 Configuration,
+ * 0x02 RST/MST, 0x80 Topology Change Notification).
+ *
+ * A Configuration / RST BPDU (type 0x00 / 0x02) then carries the full spanning-tree state — Flags, Root
+ * Identifier, Root Path Cost, Bridge Identifier, Port Identifier and the four timers (Message Age, Max
+ * Age, Hello Time, Forward Delay) — plus, for RST/MST, a trailing remainder (Version 1 Length + any MST
+ * extension) kept verbatim as `extra` hex. A TCN BPDU (type 0x80) is just the 4-byte fixed part. The
+ * body fields are decoded/encoded only for Configuration/RST types, so a TCN BPDU round-trips as exactly
+ * 4 bytes. A well-formed BPDU round-trips byte-for-byte; trailing 802.3 padding falls to RawData.
+ */
+export declare class STP 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/STP.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STP = 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");
+/**
+ * STP — Spanning Tree Protocol BPDU (IEEE 802.1D, and RSTP/MSTP 802.1w/s), carried in an 802.3 frame
+ * over LLC with DSAP/SSAP 0x42. Every BPDU opens with a 4-byte fixed part: a 2-byte Protocol Identifier
+ * (0x0000), a 1-byte Protocol Version (0 STP, 2 RSTP, 3 MSTP) and a 1-byte BPDU Type (0x00 Configuration,
+ * 0x02 RST/MST, 0x80 Topology Change Notification).
+ *
+ * A Configuration / RST BPDU (type 0x00 / 0x02) then carries the full spanning-tree state — Flags, Root
+ * Identifier, Root Path Cost, Bridge Identifier, Port Identifier and the four timers (Message Age, Max
+ * Age, Hello Time, Forward Delay) — plus, for RST/MST, a trailing remainder (Version 1 Length + any MST
+ * extension) kept verbatim as `extra` hex. A TCN BPDU (type 0x80) is just the 4-byte fixed part. The
+ * body fields are decoded/encoded only for Configuration/RST types, so a TCN BPDU round-trips as exactly
+ * 4 bytes. A well-formed BPDU round-trips byte-for-byte; trailing 802.3 padding falls to RawData.
+ */
+class STP extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'stp';
+        this.name = 'Spanning Tree Protocol';
+        this.nickname = 'STP';
+        this.matchKeys = ['llcsap:66'];
+        //A leaf — a BPDU carries no encapsulated protocol.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (STP.#schemaCache ??= STP.#buildSchema());
+    }
+    /** Configuration (0x00) and RST/MST (0x02) BPDUs carry the full body; TCN (0x80) does not. */
+    #isConfig() {
+        const type = this.instance.bpduType.getValue(0);
+        return type === 0x00 || type === 0x02;
+    }
+    /** A body field present only on Configuration/RST BPDUs — read/written verbatim, skipped for TCN. */
+    static #bodyUInt(name, offset, byteLength, label) {
+        const max = byteLength === 1 ? 255 : byteLength === 2 ? 65535 : 4294967295;
+        return {
+            type: 'integer',
+            label: label,
+            minimum: 0,
+            maximum: max,
+            decode: function () {
+                if (!this.#isConfig())
+                    return;
+                const buffer = this.readBytes(offset, byteLength);
+                const value = byteLength === 1 ? (0, BufferToNumber_1.BufferToUInt8)(buffer) : byteLength === 2 ? (0, BufferToNumber_1.BufferToUInt16)(buffer) : (0, BufferToNumber_1.BufferToUInt32)(buffer);
+                this.instance[name].setValue(value);
+            },
+            encode: function () {
+                if (!this.#isConfig())
+                    return;
+                let value = this.instance[name].getValue(0);
+                if (value > max)
+                    value = max;
+                if (value < 0)
+                    value = 0;
+                const buffer = byteLength === 1 ? (0, NumberToBuffer_1.UInt8ToBuffer)(value) : byteLength === 2 ? (0, NumberToBuffer_1.UInt16ToBuffer)(value) : (0, NumberToBuffer_1.UInt32ToBuffer)(value);
+                this.writeBytes(offset, buffer);
+            }
+        };
+    }
+    /** A verbatim-hex body field present only on Configuration/RST BPDUs (identifiers). */
+    static #bodyHex(name, offset, byteLength, label) {
+        return {
+            type: 'string',
+            label: label,
+            contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+            decode: function () {
+                if (!this.#isConfig())
+                    return;
+                this.instance[name].setValue((0, BufferToHex_1.BufferToHex)(this.readBytes(offset, byteLength)));
+            },
+            encode: function () {
+                if (!this.#isConfig())
+                    return;
+                const value = this.instance[name].getValue('');
+                if (value)
+                    this.writeBytes(offset, (0, HexToBuffer_1.HexToBuffer)(value));
+            }
+        };
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'STP type=${bpduType} version=${protocolVersion}',
+            properties: {
+                //Fixed 4-byte part, present on every BPDU.
+                protocolIdentifier: this.fieldHex('protocolIdentifier', 0, 2, 'Protocol Identifier'),
+                protocolVersion: this.fieldUInt('protocolVersion', 2, 1, 'Protocol Version'),
+                bpduType: this.fieldUInt('bpduType', 3, 1, 'BPDU Type'),
+                //Configuration / RST body (skipped for a 4-byte TCN BPDU).
+                flags: this.#bodyUInt('flags', 4, 1, 'Flags'),
+                rootIdentifier: this.#bodyHex('rootIdentifier', 5, 8, 'Root Identifier'),
+                rootPathCost: this.#bodyUInt('rootPathCost', 13, 4, 'Root Path Cost'),
+                bridgeIdentifier: this.#bodyHex('bridgeIdentifier', 17, 8, 'Bridge Identifier'),
+                portIdentifier: this.#bodyUInt('portIdentifier', 25, 2, 'Port Identifier'),
+                messageAge: this.#bodyUInt('messageAge', 27, 2, 'Message Age'),
+                maxAge: this.#bodyUInt('maxAge', 29, 2, 'Max Age'),
+                helloTime: this.#bodyUInt('helloTime', 31, 2, 'Hello Time'),
+                forwardDelay: this.#bodyUInt('forwardDelay', 33, 2, 'Forward Delay'),
+                //RST/MST trailing remainder (Version 1 Length + any MST configuration), kept verbatim.
+                //Only an RST/MST BPDU (type 0x02) carries it; a Configuration BPDU (0x00) is exactly 35
+                //bytes, so its trailing 802.3 minimum-frame padding is left to RawData rather than absorbed
+                //here (which would break the padding's own byte-perfect identity and mislabel it).
+                extra: {
+                    type: 'string',
+                    label: 'Extra',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const bpduType = this.instance.bpduType.getValue(0);
+                        if (bpduType !== 0x02)
+                            return;
+                        const available = this.packet.length - this.startPos;
+                        if (available > 35)
+                            this.instance.extra.setValue((0, BufferToHex_1.BufferToHex)(this.readBytes(35, available - 35)));
+                        else
+                            this.instance.extra.setValue('');
+                    },
+                    encode: function () {
+                        const bpduType = this.instance.bpduType.getValue(0);
+                        if (bpduType !== 0x02)
+                            return;
+                        const extra = this.instance.extra.getValue('');
+                        if (extra)
+                            this.writeBytes(35, (0, HexToBuffer_1.HexToBuffer)(extra));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //An LLC child selected by DSAP 0x42 (66). Confirm the parent is LLC and the DSAP byte is 0x42, and
+        //require the 4-byte fixed BPDU part.
+        const prev = this.prevCodecModule;
+        if (!prev || prev.id !== 'llc')
+            return false;
+        if (prev.instance.dsap.getValue(0) !== 0x42)
+            return false;
+        return this.packet.length - this.startPos >= 4;
+    }
+}
+exports.STP = STP;

package/dist/headers/STUN.d.ts

@@ -0,0 +1,25 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * STUN — Session Traversal Utilities for NAT (RFC 5389, superseded by RFC 8489 with the same wire
+ * format). A 20-byte fixed header — Message Type, Message Length, the 0x2112A442 Magic Cookie and a
+ * 96-bit Transaction ID (RFC 5389 §6) — followed by zero or more Type-Length-Value attributes
+ * (§15), each padded to a 4-byte boundary. Rides UDP/TCP, well-known port 3478.
+ *
+ * Attributes are carried generically (attribute type + verbatim hex value) so every attribute —
+ * standard or unknown — round-trips byte-for-byte; per-attribute semantic decoding (XOR-MAPPED-ADDRESS
+ * → ip:port, etc.) is a later enrichment layered on top of this faithful TLV base. Padding bytes are
+ * re-emitted as zero (RFC 5389 §15: padding bits are ignored and MAY be any value).
+ */
+export declare class STUN extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    readonly heuristicFallback: boolean;
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}

package/dist/headers/STUN.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STUN = void 0;
+const BaseHeader_1 = require("../abstracts/BaseHeader");
+const BufferToHex_1 = require("../helper/BufferToHex");
+const BufferToNumber_1 = require("../helper/BufferToNumber");
+const NumberToBuffer_1 = require("../helper/NumberToBuffer");
+const StringContentEncodingEnum_1 = require("../lib/StringContentEncodingEnum");
+/**
+ * STUN — Session Traversal Utilities for NAT (RFC 5389, superseded by RFC 8489 with the same wire
+ * format). A 20-byte fixed header — Message Type, Message Length, the 0x2112A442 Magic Cookie and a
+ * 96-bit Transaction ID (RFC 5389 §6) — followed by zero or more Type-Length-Value attributes
+ * (§15), each padded to a 4-byte boundary. Rides UDP/TCP, well-known port 3478.
+ *
+ * Attributes are carried generically (attribute type + verbatim hex value) so every attribute —
+ * standard or unknown — round-trips byte-for-byte; per-attribute semantic decoding (XOR-MAPPED-ADDRESS
+ * → ip:port, etc.) is a later enrichment layered on top of this faithful TLV base. Padding bytes are
+ * re-emitted as zero (RFC 5389 §15: padding bits are ignored and MAY be any value).
+ */
+class STUN extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'stun';
+        this.name = 'Session Traversal Utilities for NAT';
+        this.nickname = 'STUN';
+        //Well-known port 3478 (UDP and TCP). heuristicFallback because the 0x2112A442 Magic Cookie is a
+        //reliable 32-bit content signature — STUN is used on ephemeral ports too (ICE/WebRTC), so it must
+        //also be recognized off 3478 via match().
+        this.matchKeys = ['udpport:3478', 'tcpport:3478'];
+        this.heuristicFallback = true;
+        //Produces no child demux key — STUN attributes are handled internally; nothing rides above it.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (STUN.#schemaCache ??= STUN.#buildSchema());
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            properties: {
+                //Message Type (RFC 5389 §6): 14 bits of class+method, top 2 bits zero. Kept as a plain
+                //uint16 (e.g. 0x0001 Binding Request, 0x0101 Binding Success Response) — byte-perfect and
+                //editable; the class/method split is UI enrichment for later.
+                messageType: this.fieldUInt('messageType', 0, 2, 'Message Type'),
+                //Message Length: attribute bytes only (excludes the 20-byte header), including padding.
+                //Explicit non-zero is honored (a crafted wrong length is a valid packet); 0 auto-computes
+                //from the encoded attributes after they are written.
+                messageLength: {
+                    type: 'integer',
+                    label: 'Message Length',
+                    minimum: 0,
+                    maximum: 65535,
+                    decode: function () {
+                        this.instance.messageLength.setValue((0, BufferToNumber_1.BufferToUInt16)(this.readBytes(2, 2)));
+                    },
+                    encode: function () {
+                        const messageLength = this.instance.messageLength.getValue(0);
+                        if (messageLength) {
+                            this.instance.messageLength.setValue(messageLength);
+                            this.writeBytes(2, (0, NumberToBuffer_1.UInt16ToBuffer)(messageLength));
+                        }
+                        else {
+                            this.writeBytes(2, (0, NumberToBuffer_1.UInt16ToBuffer)(0));
+                            this.instance.messageLength.setValue(0);
+                            //After every field (attributes included) has encoded, the header length is
+                            //20 + attribute bytes; fill in the real Message Length.
+                            this.addPostSelfEncodeHandler(() => {
+                                const attributeBytes = this.length - 20 < 0 ? 0 : this.length - 20;
+                                this.instance.messageLength.setValue(attributeBytes);
+                                this.writeBytes(2, (0, NumberToBuffer_1.UInt16ToBuffer)(attributeBytes));
+                            }, 1);
+                        }
+                    }
+                },
+                magicCookie: this.fieldHex('magicCookie', 4, 4, 'Magic Cookie'),
+                transactionId: this.fieldHex('transactionId', 8, 12, 'Transaction ID'),
+                attributes: {
+                    type: 'array',
+                    label: 'Attributes',
+                    items: {
+                        type: 'object',
+                        label: 'Attribute',
+                        properties: {
+                            type: {
+                                type: 'integer',
+                                label: 'Attribute Type',
+                                minimum: 0,
+                                maximum: 65535
+                            },
+                            value: {
+                                type: 'string',
+                                label: 'Value',
+                                contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX
+                            },
+                            //Present only when the on-wire padding is non-zero (RFC 5389 §15 lets it be
+                            //any value); hidden from the default form since padding is not semantic.
+                            pad: {
+                                type: 'string',
+                                label: 'Padding',
+                                contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                                hidden: true
+                            }
+                        }
+                    },
+                    decode: function () {
+                        const messageLength = this.instance.messageLength.getValue(0);
+                        //Bound by BOTH the declared Message Length AND the bytes actually present, so a
+                        //lying Message Length (e.g. 0xFFFF) cannot spawn phantom attributes past the end
+                        //of the buffer. readBytes clamps at the buffer end and offset always advances by
+                        //at least 4, so the loop also cannot read out of bounds or run forever.
+                        const available = this.packet.length - this.startPos;
+                        const end = Math.min(20 + messageLength, available < 20 ? 20 : available);
+                        const attributes = [];
+                        let offset = 20;
+                        //Each attribute is Type(2) Length(2) Value(Length) then padding to a 4-byte boundary.
+                        while (offset + 4 <= end) {
+                            const type = (0, BufferToNumber_1.BufferToUInt16)(this.readBytes(offset, 2));
+                            const length = (0, BufferToNumber_1.BufferToUInt16)(this.readBytes(offset + 2, 2));
+                            offset += 4;
+                            let value = Buffer.alloc(0);
+                            if (length) {
+                                value = this.readBytes(offset, length);
+                                offset += length;
+                            }
+                            const padLength = (4 - length % 4) % 4;
+                            const attribute = { type: type, value: (0, BufferToHex_1.BufferToHex)(value) };
+                            //Consume the padding so the header length covers it (endPos is exact). Keep
+                            //the actual bytes only when non-zero, so a byte round-trip is exact for the
+                            //rare legal non-zero padding without polluting the common zero-padded case.
+                            if (padLength) {
+                                const padding = this.readBytes(offset, padLength);
+                                offset += padLength;
+                                if (padding.some((byte) => byte !== 0))
+                                    attribute.pad = (0, BufferToHex_1.BufferToHex)(padding);
+                            }
+                            attributes.push(attribute);
+                        }
+                        this.instance.attributes.setValue(attributes);
+                    },
+                    encode: function () {
+                        const attributes = this.instance.attributes.getValue();
+                        if (!attributes)
+                            return;
+                        let offset = 20;
+                        attributes.forEach((attribute) => {
+                            const type = attribute.type ? attribute.type : 0;
+                            const value = Buffer.from(attribute.value ? attribute.value : '', 'hex');
+                            const length = value.length;
+                            this.writeBytes(offset, (0, NumberToBuffer_1.UInt16ToBuffer)(type));
+                            this.writeBytes(offset + 2, (0, NumberToBuffer_1.UInt16ToBuffer)(length));
+                            offset += 4;
+                            if (length) {
+                                this.writeBytes(offset, value);
+                                offset += length;
+                            }
+                            const padLength = (4 - length % 4) % 4;
+                            if (padLength) {
+                                //Re-emit preserved non-zero padding verbatim (sized to padLength: extra
+                                //dropped, short zero-filled); default zeros when none was carried.
+                                const padding = Buffer.alloc(padLength, 0);
+                                if (attribute.pad)
+                                    Buffer.from(attribute.pad, 'hex').copy(padding, 0, 0, padLength);
+                                this.writeBytes(offset, padding);
+                                offset += padLength;
+                            }
+                        });
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        if (!this.prevCodecModule)
+            return false;
+        //Magic Cookie 0x2112A442 at offset 4 (RFC 5389 §6). A 32-bit signature — safe to match on any
+        //port. RFC 3489 classic STUN (no cookie) is intentionally not matched.
+        if (this.packet.length - this.startPos < 8)
+            return false;
+        return (0, BufferToHex_1.BufferToHex)(this.readBytes(4, 4)) === '2112a442';
+    }
+}
+exports.STUN = STUN;

package/dist/headers/SercosIII.d.ts

@@ -0,0 +1,43 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * Sercos III — the real-time industrial Ethernet of the Sercos automation bus (IEC 61491 / IEC 61158,
+ * IEC 61784 CPF-16), carried directly in an Ethernet II frame with EtherType 0x88CD (an Ethernet child —
+ * no IP/UDP). Every communication cycle the master emits Master Data Telegrams (MDT) and the slaves answer
+ * with Acknowledge Telegrams (AT); both frame kinds share the same EtherType and are distinguished by the
+ * Telegram Type bit in the first header byte.
+ *
+ * The frame opens with the Sercos III telegram header. This minimal slice structures the fixed leading
+ * bytes and keeps the per-device payload verbatim:
+ *
+ *   Byte 0 — Telegram Type field (a bitfield, MSB-first per the Wireshark `siii` dissector):
+ *     - bit 7 (0x80) channel          — 0 = P-Telegram (primary line), 1 = S-Telegram (secondary line)
+ *     - bit 6 (0x40) telegramType      — 0 = MDT (Master Data Telegram), 1 = AT (Acknowledge Telegram)
+ *     - bit 5 (0x20) cycleCountValid   — the MST cycle count is valid
+ *     - bit 4 (0x10) reserved          — preserved verbatim for a byte-perfect round-trip
+ *     - bits 0..3 (0x0f) telegramNumber— MDT/AT index within the cycle (0..15)
+ *   Byte 1 — Phase field (the Master Sync Telegram, MST):
+ *     - the Phase occupies mask 0x8f (bit 7 = phase switching, bits 0..3 = communication phase CP0..CP4),
+ *       a non-contiguous field kept as one value; the Cycle Count occupies mask 0x70 (bits 4..6).
+ *   Bytes 2..5 — CRC32 of the MST, kept verbatim (little-endian on the wire per the dissector) and never
+ *     recomputed, so a captured frame round-trips byte-for-byte.
+ *
+ * Everything after the 6-byte header (the phase-dependent per-device connection / service-channel data) is
+ * command- and topology-dependent, so this slice keeps it verbatim as `data` hex (byte-perfect), bounded by
+ * the end of the Ethernet payload (Sercos III has no length field of its own — it runs to the end of the
+ * frame, like LLDP/GOOSE). Structuring the per-device bodies (device control/status, service channel, hot
+ * plug) is a deferred slice. The MST header is genuine for the CP0–CP2 scanning phases and MDT0; for a
+ * CP3/CP4 operational device telegram the byte-1..5 labels are nominal but the bytes are still reproduced
+ * exactly because every header field is read and re-emitted verbatim.
+ */
+export declare class SercosIII extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}