@netkitty/codec 1.0.0

package/dist/headers/POP3.js

@@ -0,0 +1,152 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POP3 = 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");
+/** POP3 command verbs (RFC 1939 + STLS/CAPA extensions) used only to recognize a command line. */
+const POP3_COMMANDS = ['USER', 'PASS', 'APOP', 'STAT', 'LIST', 'RETR', 'DELE', 'NOOP', 'RSET', 'QUIT', 'TOP', 'UIDL', 'CAPA', 'STLS'];
+/**
+ * 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.
+ */
+class POP3 extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'pop3';
+        this.name = 'Post Office Protocol v3';
+        this.nickname = 'POP3';
+        //POP3 is recognized ONLY on its well-known port buckets (110, and 995 for TLS-wrapped POP3S) —
+        //deliberately NOT via heuristicFallback. Unlike HTTP/RTSP (whose method sets are distinctive), POP3's
+        //line signature is a `+OK`/`-ERR` status or a generic verb (USER/PASS/STAT/LIST/RETR/QUIT/…) that is
+        //SHARED with other US-ASCII line protocols this codec also models — FTP (USER/PASS/STAT/LIST/RETR/
+        //QUIT). Joining the global heuristic chain would let POP3 mislabel an FTP `USER`/`STAT`/`RETR` line
+        //on tcp:21 as POP3 (and vice-versa). Confining POP3 to its tcp:110/tcp:995 buckets keeps that
+        //collision impossible (FTP lives on 21, which never reaches these buckets); alt-port POP3 is rare and
+        //falls losslessly to raw. (POP3S on 995 is normally TLS-wrapped, so the bucket rarely carries plain
+        //POP3 text, but is listed for completeness/STLS-downgrade traffic.)
+        this.matchKeys = ['tcpport:110', 'tcpport:995'];
+        //A leaf header — the POP3 session it belongs to is a higher-layer concern.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (_a.#schemaCache ??= _a.#buildSchema());
+    }
+    /**
+     * Bytes of this header: POP3 rides on TCP, which has no per-message length, so take the rest of the
+     * segment. Reassembly across segments is out of scope (see class doc).
+     */
+    #payloadLength() {
+        const available = this.packet.length - this.startPos;
+        return available < 0 ? 0 : available;
+    }
+    /** The first line of the message (up to the first CRLF, or the whole payload if none). */
+    static #firstLine(text) {
+        const idx = text.indexOf('\r\n');
+        return idx >= 0 ? text.slice(0, idx) : text;
+    }
+    /**
+     * Parse the first line into the display-only metadata fields. A line beginning with `+OK` or `-ERR`
+     * is a server reply (the status indicator and the trailing text); anything else is a client command
+     * (the uppercased verb and its argument). Populated on decode only — these fields have no encode, so
+     * they never affect the re-emitted bytes and never mutate `message`. Never throws: missing/garbage
+     * tokens yield empty strings.
+     */
+    #parseFirstLine(text) {
+        const line = _a.#firstLine(text);
+        const reply = line.match(/^(\+OK|-ERR)(?: (.*))?$/);
+        if (reply) {
+            //Reply: a status indicator (+OK success / -ERR failure), then optional trailing text.
+            this.instance.isReply.setValue(true);
+            this.instance.status.setValue(reply[1]);
+            this.instance.replyText.setValue(reply[2] ?? '');
+            this.instance.command.setValue('');
+            this.instance.argument.setValue('');
+            return;
+        }
+        //Command: VERB SP argument (the argument may itself contain spaces, e.g. `APOP name digest`).
+        const idx = line.indexOf(' ');
+        const verb = idx >= 0 ? line.slice(0, idx) : line;
+        this.instance.isReply.setValue(false);
+        this.instance.status.setValue('');
+        this.instance.replyText.setValue('');
+        this.instance.command.setValue(verb.toUpperCase());
+        this.instance.argument.setValue(idx >= 0 ? line.slice(idx + 1) : '');
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'POP3 ${command}${status}',
+            properties: {
+                //The whole raw message is the single source of truth: decoded verbatim to hex and
+                //re-emitted untouched (byte-perfect for any POP3 control text). The first line is parsed
+                //into the display-only metadata below, which carry no codec of their own.
+                message: {
+                    type: 'string',
+                    label: 'Message',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const available = this.#payloadLength();
+                        if (available <= 0) {
+                            this.instance.message.setValue('');
+                            this.#parseFirstLine('');
+                            return;
+                        }
+                        const raw = this.readBytes(0, available);
+                        this.instance.message.setValue((0, BufferToHex_1.BufferToHex)(raw));
+                        this.#parseFirstLine(raw.toString('latin1'));
+                    },
+                    encode: function () {
+                        //Re-emit the authoritative message verbatim — never reconstruct from metadata.
+                        this.writeBytes(0, (0, HexToBuffer_1.HexToBuffer)(this.instance.message.getValue('')));
+                    }
+                },
+                //Display-only metadata parsed from the first line on decode (no encode — populated by the
+                //message field above, never read back). isReply distinguishes a server reply from a
+                //client command; status/replyText describe a reply, command/argument a command.
+                isReply: { type: 'boolean', label: 'Is Reply' },
+                status: { type: 'string', label: 'Status' },
+                replyText: { type: 'string', label: 'Reply Text' },
+                command: { type: 'string', label: 'Command' },
+                argument: { type: 'string', label: 'Argument' }
+            }
+        };
+    }
+    match() {
+        //POP3 rides on TCP as US-ASCII text. Recognize it by the line signature: a `+OK`/`-ERR` status
+        //indicator, or a known command verb as the leading token (up to the first space or CR) — so
+        //non-POP3 traffic on port 110/995 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() < 3)
+            return false;
+        const lead = this.readBytes(0, 16, true).toString('latin1');
+        if (/^(\+OK|-ERR)/.test(lead))
+            return true;
+        const line = _a.#firstLine(lead);
+        const token = (line.split(/[ \r]/)[0] || '').toUpperCase();
+        return POP3_COMMANDS.includes(token);
+    }
+}
+exports.POP3 = POP3;
+_a = POP3;

package/dist/headers/POWERLINK.d.ts

@@ -0,0 +1,28 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * Ethernet POWERLINK (EPL, EPSG DS 301 / IEC 61784-2 CPF 13), a real-time industrial Ethernet protocol
+ * carried directly in an Ethernet II frame with EtherType 0x88AB (an Ethernet child — no IP/UDP). Every
+ * EPL basic frame begins with a fixed 3-byte common header: a 1-byte MessageType octet (bit 7 Reserved,
+ * bits 6..0 the 7-bit message type), a 1-byte Destination node id, and a 1-byte Source node id. The
+ * message types are SoC = 1 (Start of Cycle), PReq = 3 (Poll Request), PRes = 4 (Poll Response),
+ * SoA = 5 (Start of Asynchronous), ASnd = 6 (Asynchronous Send). The type-specific body follows.
+ *
+ * EPL has no length field of its own — a basic frame runs to the end of the Ethernet frame (short frames
+ * are Ethernet-padded to the 60-byte minimum). The per-type body layouts (SoC NetTime/RelativeTime, PReq/
+ * PRes flags+PDO payload, SoA service request, ASnd service data) differ and several carry variable
+ * mapped-PDO data, so this minimal slice decodes only the 3-byte common header structurally and keeps the
+ * remainder — body plus any trailing Ethernet padding — verbatim as `payload` hex (byte-perfect, a
+ * self-contained leaf, so nothing depends on RawData). A well-formed frame round-trips byte-for-byte.
+ */
+export declare class POWERLINK 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/POWERLINK.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POWERLINK = 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");
+/**
+ * Ethernet POWERLINK (EPL, EPSG DS 301 / IEC 61784-2 CPF 13), a real-time industrial Ethernet protocol
+ * carried directly in an Ethernet II frame with EtherType 0x88AB (an Ethernet child — no IP/UDP). Every
+ * EPL basic frame begins with a fixed 3-byte common header: a 1-byte MessageType octet (bit 7 Reserved,
+ * bits 6..0 the 7-bit message type), a 1-byte Destination node id, and a 1-byte Source node id. The
+ * message types are SoC = 1 (Start of Cycle), PReq = 3 (Poll Request), PRes = 4 (Poll Response),
+ * SoA = 5 (Start of Asynchronous), ASnd = 6 (Asynchronous Send). The type-specific body follows.
+ *
+ * EPL has no length field of its own — a basic frame runs to the end of the Ethernet frame (short frames
+ * are Ethernet-padded to the 60-byte minimum). The per-type body layouts (SoC NetTime/RelativeTime, PReq/
+ * PRes flags+PDO payload, SoA service request, ASnd service data) differ and several carry variable
+ * mapped-PDO data, so this minimal slice decodes only the 3-byte common header structurally and keeps the
+ * remainder — body plus any trailing Ethernet padding — verbatim as `payload` hex (byte-perfect, a
+ * self-contained leaf, so nothing depends on RawData). A well-formed frame round-trips byte-for-byte.
+ */
+class POWERLINK extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'powerlink';
+        this.name = 'Ethernet POWERLINK';
+        this.nickname = 'POWERLINK';
+        this.matchKeys = ['ethertype:88ab'];
+        //A leaf header — the per-type body is kept verbatim as `payload`; nothing demuxes above POWERLINK.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (POWERLINK.#schemaCache ??= POWERLINK.#buildSchema());
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'POWERLINK mtype=${messageType} ${source}->${destination}',
+            properties: {
+                //MessageType octet (byte 0): the high bit (0x80) is Reserved, kept verbatim so a frame that
+                //sets it still round-trips; the low 7 bits (0x7F, epl.mtyp) carry the message type.
+                reserved: {
+                    type: 'integer',
+                    label: 'Reserved',
+                    minimum: 0,
+                    maximum: 1,
+                    hidden: true,
+                    decode: function () {
+                        this.instance.reserved.setValue(this.readBits(0, 1, 0, 1));
+                    },
+                    encode: function () {
+                        this.writeBits(0, 1, 0, 1, this.instance.reserved.getValue(0));
+                    }
+                },
+                messageType: {
+                    type: 'integer',
+                    label: 'Message Type',
+                    minimum: 0,
+                    maximum: 127,
+                    decode: function () {
+                        this.instance.messageType.setValue(this.readBits(0, 1, 1, 7));
+                    },
+                    encode: function () {
+                        const node = this.instance.messageType;
+                        let value = node.getValue(0, (nodePath) => this.recordError(nodePath, 'Not Found'));
+                        //A 7-bit field cannot represent a value above 127 — clamp (recording the error)
+                        //rather than let it wrap into the Reserved bit and corrupt byte 0.
+                        if (value > 127) {
+                            this.recordError(node.getPath(), 'Maximum value is 127');
+                            value = 127;
+                        }
+                        if (value < 0) {
+                            this.recordError(node.getPath(), 'Minimum value is 0');
+                            value = 0;
+                        }
+                        node.setValue(value);
+                        this.writeBits(0, 1, 1, 7, value);
+                    }
+                },
+                destination: this.fieldUInt('destination', 1, 1, 'Destination Node'),
+                source: this.fieldUInt('source', 2, 1, 'Source Node'),
+                //The type-specific body plus any trailing Ethernet padding, kept verbatim. EPL has no
+                //length field, so — like LLDP — the frame runs to its end; the whole remainder after the
+                //3-byte common header is this layer's own bytes (a self-contained leaf), bounded by the
+                //captured frame so a truncated frame still round-trips exactly.
+                payload: {
+                    type: 'string',
+                    label: 'Payload',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const available = this.packet.length - this.startPos;
+                        this.instance.payload.setValue(available > 3 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(3, available - 3)) : '');
+                    },
+                    encode: function () {
+                        const payload = this.instance.payload.getValue('');
+                        if (payload)
+                            this.writeBytes(3, (0, HexToBuffer_1.HexToBuffer)(payload));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //An Ethernet child selected by EtherType 0x88AB (stored as a lowercase 4-hex string). Not gated on
+        //prevCodecModule.id so an EPL frame nested under a VLAN/HSR tag is still recognized. Require the
+        //3-byte common header (MessageType + Destination + Source).
+        if (!this.prevCodecModule)
+            return false;
+        if (this.prevCodecModule.instance.etherType.getValue() !== '88ab')
+            return false;
+        return this.packet.length - this.startPos >= 3;
+    }
+}
+exports.POWERLINK = POWERLINK;

package/dist/headers/PPPoEDiscovery.d.ts

@@ -0,0 +1,29 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * PPPoE Discovery Stage (RFC 2516), carried directly in an Ethernet II frame with EtherType 0x8863 (an
+ * Ethernet child — no IP/UDP). The 6-byte header is a Version (high 4 bits, 1) + Type (low 4 bits, 1)
+ * octet, a 1-byte Code (0x09 PADI, 0x07 PADO, 0x19 PADR, 0x65 PADS, 0xa7 PADT), a 2-byte Session ID,
+ * and a 2-byte Length that counts only the tag payload that follows. The payload is a flat sequence of
+ * TLV tags — Type (2 bytes: 0x0101 Service-Name, 0x0102 AC-Name, 0x0103 Host-Uniq, 0x0104 AC-Cookie,
+ * 0x0000 End-Of-List) + Length (2 bytes, the value byte count) + Length value bytes — bounded by the
+ * header Length field.
+ *
+ * Tags are carried generically (type + honored per-tag length + verbatim hex value) so every tag —
+ * including opaque/vendor tags — round-trips byte-for-byte; per-tag semantic decoding is a later
+ * enrichment. The header Length is honored when supplied (a crafted frame may lie) and otherwise
+ * derived from the on-wire tag bytes. The tag walk is bounded by that Length; any trailing bytes (an
+ * Ethernet minimum-frame pad) are kept verbatim in `padding` so the frame reproduces exactly. A leaf
+ * header — the Discovery stage carries no encapsulated payload.
+ */
+export declare class PPPoEDiscovery 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/PPPoEDiscovery.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PPPoEDiscovery = 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");
+/**
+ * PPPoE Discovery Stage (RFC 2516), carried directly in an Ethernet II frame with EtherType 0x8863 (an
+ * Ethernet child — no IP/UDP). The 6-byte header is a Version (high 4 bits, 1) + Type (low 4 bits, 1)
+ * octet, a 1-byte Code (0x09 PADI, 0x07 PADO, 0x19 PADR, 0x65 PADS, 0xa7 PADT), a 2-byte Session ID,
+ * and a 2-byte Length that counts only the tag payload that follows. The payload is a flat sequence of
+ * TLV tags — Type (2 bytes: 0x0101 Service-Name, 0x0102 AC-Name, 0x0103 Host-Uniq, 0x0104 AC-Cookie,
+ * 0x0000 End-Of-List) + Length (2 bytes, the value byte count) + Length value bytes — bounded by the
+ * header Length field.
+ *
+ * Tags are carried generically (type + honored per-tag length + verbatim hex value) so every tag —
+ * including opaque/vendor tags — round-trips byte-for-byte; per-tag semantic decoding is a later
+ * enrichment. The header Length is honored when supplied (a crafted frame may lie) and otherwise
+ * derived from the on-wire tag bytes. The tag walk is bounded by that Length; any trailing bytes (an
+ * Ethernet minimum-frame pad) are kept verbatim in `padding` so the frame reproduces exactly. A leaf
+ * header — the Discovery stage carries no encapsulated payload.
+ */
+class PPPoEDiscovery extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'pppoe-disc';
+        this.name = 'PPP-over-Ethernet Discovery';
+        this.nickname = 'PPPoED';
+        this.matchKeys = ['ethertype:8863'];
+        //A leaf header — the Discovery stage carries no encapsulated payload (session data uses EtherType
+        //0x8864, a separate header).
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (PPPoEDiscovery.#schemaCache ??= PPPoEDiscovery.#buildSchema());
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'PPPoE Discovery code=${code} session=${sessionId}',
+            properties: {
+                //Byte 0 high nibble: PPPoE Version (1). Written MSB-first; shares byte 0 with Type
+                //(writeBits masks each field so they never clobber).
+                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(1);
+                        this.instance.version.setValue(value);
+                        this.writeBits(0, 1, 0, 4, value);
+                    }
+                },
+                //Byte 0 low nibble: PPPoE Type (1).
+                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(1);
+                        this.instance.type.setValue(value);
+                        this.writeBits(0, 1, 4, 4, value);
+                    }
+                },
+                //Code (byte 1): 0x09 PADI, 0x07 PADO, 0x19 PADR, 0x65 PADS, 0xa7 PADT.
+                code: this.fieldUInt('code', 1, 1, 'Code'),
+                //Session ID (bytes 2-3): 0x0000 during discovery until the AC assigns it in PADS.
+                sessionId: this.fieldUInt('sessionId', 2, 2, 'Session ID'),
+                length: {
+                    type: 'integer',
+                    label: 'Payload Length',
+                    minimum: 0,
+                    maximum: 65535,
+                    decode: function () {
+                        this.instance.length.setValue((0, BufferToNumber_1.BufferToUInt16)(this.readBytes(4, 2)));
+                    },
+                    encode: function () {
+                        //Length counts only the tag payload (not the 6-byte header). Honored when supplied
+                        //(a crafted frame may lie); else derived from the actual on-wire tag bytes, which is
+                        //what the tags field emits — sum of (4-byte tag header + value byte count) per tag.
+                        const provided = this.instance.length.getValue();
+                        let value;
+                        if (provided !== undefined && provided !== null) {
+                            value = provided;
+                        }
+                        else {
+                            const tags = this.instance.tags.getValue([]);
+                            let total = 0;
+                            for (const tag of (tags ? tags : [])) {
+                                total += 4 + (0, HexToBuffer_1.HexToBuffer)(tag.value ? tag.value : '').length;
+                            }
+                            value = total;
+                        }
+                        if (value > 65535) {
+                            this.recordError(this.instance.length.getPath(), 'Maximum value is 65535');
+                            value = 65535;
+                        }
+                        this.instance.length.setValue(value);
+                        this.writeBytes(4, (0, NumberToBuffer_1.UInt16ToBuffer)(value));
+                    }
+                },
+                tags: {
+                    type: 'array',
+                    label: 'Tags',
+                    items: {
+                        type: 'object',
+                        label: 'Tag',
+                        properties: {
+                            type: { type: 'integer', label: 'Type', minimum: 0, maximum: 65535 },
+                            length: { type: 'integer', label: 'Length', minimum: 0, maximum: 65535, hidden: true },
+                            value: { type: 'string', label: 'Value', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX }
+                        }
+                    },
+                    decode: function () {
+                        //Bound the tag walk by the header Length (from offset 6), clamped down to the bytes
+                        //actually present in the frame so a lying Length can't read past the buffer.
+                        const available = this.packet.length - this.startPos;
+                        let end = 6 + this.instance.length.getValue(0);
+                        if (end > available)
+                            end = available;
+                        if (end < 6)
+                            end = 6;
+                        const tags = [];
+                        let offset = 6;
+                        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));
+                            //A value that overruns the bounded region (truncation) is not consumed — stop and
+                            //leave the remaining bytes to `padding`, keeping the round-trip exact.
+                            if (offset + 4 + length > end)
+                                break;
+                            const value = length > 0 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(offset + 4, length)) : '';
+                            tags.push({ type: type, length: length, value: value });
+                            offset += 4 + length;
+                        }
+                        this.instance.tags.setValue(tags);
+                        //Trailing bytes after the last consumed tag (Ethernet minimum-frame padding, or a
+                        //truncated tag) are kept verbatim so the frame is reproduced exactly.
+                        this.instance.padding.setValue(offset < available ? (0, BufferToHex_1.BufferToHex)(this.readBytes(offset, available - offset)) : '');
+                    },
+                    encode: function () {
+                        const tags = this.instance.tags.getValue([]);
+                        let offset = 6;
+                        if (tags) {
+                            for (let i = 0; i < tags.length; i++) {
+                                const tag = tags[i];
+                                const value = (0, HexToBuffer_1.HexToBuffer)(tag.value ? tag.value : '');
+                                //Per-tag Length is honored when supplied (a crafted tag may lie about its
+                                //declared length); else derived from the actual value byte count. The value
+                                //bytes are always written verbatim regardless of the declared Length.
+                                let length = (tag.length !== undefined && tag.length !== null) ? tag.length : value.length;
+                                if (length > 65535) {
+                                    this.recordError(`tags[${i}].length`, 'Maximum value is 65535');
+                                    length = 65535;
+                                }
+                                this.writeBytes(offset, (0, NumberToBuffer_1.UInt16ToBuffer)(tag.type ? tag.type : 0));
+                                this.writeBytes(offset + 2, (0, NumberToBuffer_1.UInt16ToBuffer)(length));
+                                offset += 4;
+                                if (value.length) {
+                                    this.writeBytes(offset, value);
+                                    offset += value.length;
+                                }
+                            }
+                        }
+                        const padding = this.instance.padding.getValue('');
+                        if (padding)
+                            this.writeBytes(offset, (0, HexToBuffer_1.HexToBuffer)(padding));
+                    }
+                },
+                //Ethernet minimum-frame padding after the tags, kept verbatim. No codec of its own — it is
+                //set/read by the `tags` field (which owns the single offset walk); this entry is metadata so
+                //the editor sees the padding bytes.
+                padding: {
+                    type: 'string',
+                    label: 'Padding',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX
+                }
+            }
+        };
+    }
+    match() {
+        //An Ethernet child selected by EtherType 0x8863 (stored as a lower-case 4-hex string, as
+        //eth.etherType / a VLAN's inner etherType). Not restricted to a direct 'eth' parent so a
+        //VLAN-tagged discovery frame still matches. Require the 6-byte fixed header.
+        if (!this.prevCodecModule)
+            return false;
+        if (this.prevCodecModule.instance.etherType.getValue() !== '8863')
+            return false;
+        return this.packet.length - this.startPos >= 6;
+    }
+}
+exports.PPPoEDiscovery = PPPoEDiscovery;

package/dist/headers/PPPoESession.d.ts

@@ -0,0 +1,28 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * PPPoE Session Stage (RFC 2516), carried directly in an Ethernet II frame with EtherType 0x8864 (an
+ * Ethernet child — no IP/UDP). The 6-byte PPPoE header is a byte holding Version (high 4 bits, 1) and
+ * Type (low 4 bits, 1), a 1-byte Code (0x00 in the Session Stage), a 2-byte Session ID (non-zero), and
+ * a 2-byte Length (the octet count of the PPPoE payload — i.e. the PPP portion, which starts with the
+ * 2-byte PPP Protocol field). The payload follows: a 2-byte PPP Protocol (e.g. 0x0021 IPv4, 0x0057
+ * IPv6, 0xc021 LCP, 0x8021 IPCP) and its data.
+ *
+ * This minimal slice decodes the 6-byte header plus the 2-byte PPP Protocol and keeps the PPP data
+ * verbatim as `payload` hex (byte-perfect), bounded by the Length field so trailing Ethernet padding is
+ * left to the codec's recursion / RawData. The Length is honored verbatim when supplied (a crafted
+ * frame may lie) else derived from the actual payload (2-byte Protocol + data). A well-formed frame
+ * round-trips byte-for-byte. Inner IPv4/IPv6/LCP recursion is deferred to a serial follow-up (it needs
+ * a pppProtocol-driven demux into IPv4/IPv6.match); for now the PPP payload is a bounded-hex leaf.
+ */
+export declare class PPPoESession extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}