@netkitty/codec 1.0.0

package/dist/headers/WakeOnLAN.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WakeOnLAN = 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");
+/**
+ * Wake-on-LAN "magic packet" (AMD Magic Packet Technology), carried directly in an Ethernet II frame
+ * with EtherType 0x0842 (an Ethernet child — no IP/UDP). The magic packet has a fixed shape: a 6-byte
+ * synchronization stream of all ones (0xFF ×6), followed by the target adapter's 6-byte MAC address
+ * repeated exactly 16 times (96 bytes), optionally followed by a 0/4/6-byte SecureOn password. There is
+ * no length field — the payload runs to the end of the frame.
+ *
+ * The 16 MAC repetitions are, by definition, identical, so the target MAC is surfaced once (decoded from
+ * the first repetition) and re-emitted 16× on encode — a well-formed magic packet round-trips
+ * byte-for-byte. The 6-byte sync stream is kept verbatim as hex (so an odd/crafted stream still
+ * reproduces) and any trailing SecureOn password bytes are kept verbatim as hex (0/4/6 bytes; taken to
+ * the end of the frame). Nothing is recomputed on encode. WoL is a leaf header — nothing rides above it.
+ *
+ * Note: WoL magic packets are also frequently sent as the payload of a UDP datagram (well-known ports 9
+ * and 7, or 0). This codec handles only the EtherType 0x0842 direct-on-Ethernet framing; the UDP-carried
+ * form is a separate demux (udpport) and is not attempted here.
+ */
+class WakeOnLAN extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'wol';
+        this.name = 'Wake-on-LAN';
+        this.nickname = 'WoL';
+        this.matchKeys = ['ethertype:0842'];
+        //A leaf header — nothing demuxes above Wake-on-LAN.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (WakeOnLAN.#schemaCache ??= WakeOnLAN.#buildSchema());
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'WoL target=${targetMac}',
+            properties: {
+                //The 6-byte synchronization stream. In a well-formed magic packet it is all ones
+                //(0xFF ×6); kept verbatim as hex so a crafted stream still round-trips byte-for-byte.
+                syncStream: this.fieldHex('syncStream', 0, 6, 'Sync Stream'),
+                //The target adapter's MAC address, decoded from the first of the 16 identical repetitions
+                //(offset 6). On encode it is written back 16 times over offsets 6..101 (96 bytes) — the
+                //defining property of a magic packet, so a well-formed packet reproduces exactly.
+                targetMac: {
+                    type: 'string',
+                    label: 'Target MAC',
+                    minLength: 17,
+                    maxLength: 17,
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.MAC,
+                    decode: function () {
+                        //Read (consume) the whole 96-byte MAC block so the header length covers all 16
+                        //repetitions; the value is taken from the first repetition (they are identical).
+                        const block = this.readBytes(6, 96);
+                        this.instance.targetMac.setValue(Array.from(block.subarray(0, 6))
+                            .map((value) => value.toString(16).padStart(2, '0'))
+                            .join(':'));
+                    },
+                    encode: function () {
+                        const mac = this.instance.targetMac
+                            .getValue('00:00:00:00:00:00', (nodePath) => this.recordError(nodePath, 'Not Found'))
+                            .toString()
+                            .split(':')
+                            .map((value) => parseInt(value, 16))
+                            .map((value) => value ? value : 0);
+                        const macBuffer = Buffer.alloc(6, Buffer.from(mac));
+                        //Re-emit the 6-byte MAC 16 times (offsets 6..101) — the magic-packet MAC block.
+                        for (let i = 0; i < 16; i++)
+                            this.writeBytes(6 + i * 6, macBuffer);
+                    }
+                },
+                //Optional SecureOn password after the 96-byte MAC block (0/4/6 bytes, RFC-less vendor
+                //extension). Kept verbatim as hex, taken to the end of the frame; empty when absent.
+                //WoL is a leaf so it consumes to the end — nothing is left for the codec's recursion.
+                password: {
+                    type: 'string',
+                    label: 'SecureOn Password',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const available = this.packet.length - this.startPos;
+                        this.instance.password.setValue(available > 102 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(102, available - 102)) : '');
+                    },
+                    encode: function () {
+                        const password = this.instance.password.getValue('');
+                        if (password)
+                            this.writeBytes(102, (0, HexToBuffer_1.HexToBuffer)(password));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //An Ethernet child selected by EtherType 0x0842 (stored as a lowercase 4-hex string). Require the
+        //full sync stream + MAC block (6 + 96 = 102 bytes) and the all-ones 6-byte sync-stream signature,
+        //so non-magic 0x0842 traffic falls through to raw.
+        if (!this.prevCodecModule || this.prevCodecModule.id !== 'eth')
+            return false;
+        if (this.prevCodecModule.instance.etherType.getValue() !== '0842')
+            return false;
+        if (this.packet.length - this.startPos < 102)
+            return false;
+        const sync = this.readBytes(0, 6, true);
+        for (let i = 0; i < 6; i++) {
+            if (sync[i] !== 0xff)
+                return false;
+        }
+        //A valid magic packet repeats the target MAC identically 16 times. Since this codec re-emits the
+        //block by reconstructing it from a single MAC, a frame whose 16 repetitions are NOT all identical
+        //could not round-trip byte-for-byte — so it is not a magic packet: leave it to RawData rather than
+        //claim it and silently rewrite the block.
+        const block = this.readBytes(6, 96, true);
+        for (let rep = 1; rep < 16; rep++) {
+            for (let b = 0; b < 6; b++) {
+                if (block[rep * 6 + b] !== block[b])
+                    return false;
+            }
+        }
+        return true;
+    }
+}
+exports.WakeOnLAN = WakeOnLAN;

package/dist/headers/WebSocket.d.ts

@@ -0,0 +1,26 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * WebSocket — the RFC 6455 framing (post-HTTP-Upgrade). A frame is: byte 0 = FIN (1) + 3 reserved bits +
+ * a 4-bit Opcode (0 continuation, 1 text, 2 binary, 8 close, 9 ping, 10 pong); byte 1 = MASK (1) + a
+ * 7-bit payload length; an extended length (2 bytes if the 7-bit length is 126, 8 bytes if 127); a 4-byte
+ * masking key when MASK is set; then the (masked) application payload.
+ *
+ * WebSocket is NOT auto-registered in the default codec: which TCP stream is a WebSocket is decided by a
+ * prior HTTP `Upgrade` handshake — cross-packet state a single-packet stateless codec cannot track — so
+ * matching a frame on content alone would over-claim ordinary TCP payloads. It is therefore a
+ * decode-as-only frame codec: reachable via `new Codec([WebSocket])` (or a future upgrade-aware
+ * reassembly layer). The frame itself round-trips byte-for-byte; the payload is kept verbatim (masked
+ * bytes are not unmasked — that would change the bytes and break the round-trip).
+ */
+export declare class WebSocket 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/WebSocket.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocket = 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");
+/**
+ * WebSocket — the RFC 6455 framing (post-HTTP-Upgrade). A frame is: byte 0 = FIN (1) + 3 reserved bits +
+ * a 4-bit Opcode (0 continuation, 1 text, 2 binary, 8 close, 9 ping, 10 pong); byte 1 = MASK (1) + a
+ * 7-bit payload length; an extended length (2 bytes if the 7-bit length is 126, 8 bytes if 127); a 4-byte
+ * masking key when MASK is set; then the (masked) application payload.
+ *
+ * WebSocket is NOT auto-registered in the default codec: which TCP stream is a WebSocket is decided by a
+ * prior HTTP `Upgrade` handshake — cross-packet state a single-packet stateless codec cannot track — so
+ * matching a frame on content alone would over-claim ordinary TCP payloads. It is therefore a
+ * decode-as-only frame codec: reachable via `new Codec([WebSocket])` (or a future upgrade-aware
+ * reassembly layer). The frame itself round-trips byte-for-byte; the payload is kept verbatim (masked
+ * bytes are not unmasked — that would change the bytes and break the round-trip).
+ */
+class WebSocket extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'websocket';
+        this.name = 'WebSocket';
+        this.nickname = 'WS';
+        //Decode-as-only: no matchKeys (never auto-selected). When explicitly added via new Codec([WebSocket])
+        //it claims a TCP payload whose first two bytes are a plausible frame (a valid opcode, no reserved
+        //bits) — enough to guard against obvious non-frames while the caller has opted in.
+        this.matchKeys = [];
+        //A leaf — the payload is application data (possibly masked), kept verbatim.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (WebSocket.#schemaCache ??= WebSocket.#buildSchema());
+    }
+    /** Number of extended-length bytes implied by the 7-bit length: 2 for 126, 8 for 127, else 0. */
+    #extendedLengthBytes() {
+        const payloadLen = this.instance.payloadLen.getValue(0);
+        return payloadLen === 126 ? 2 : payloadLen === 127 ? 8 : 0;
+    }
+    /** Offset where the masking key (if any) begins: after byte 0/1 and the extended length. */
+    #maskOffset() {
+        return 2 + this.#extendedLengthBytes();
+    }
+    /** Offset where the payload begins: after the masking key when MASK is set. */
+    #payloadOffset() {
+        return this.#maskOffset() + (this.instance.mask.getValue(false) ? 4 : 0);
+    }
+    /** A single boolean bit within `byteOffset` at MSB-relative `bitOffset`. */
+    static #bitField(name, byteOffset, bitOffset, label) {
+        return {
+            type: 'boolean',
+            label: label,
+            decode: function () {
+                this.instance[name].setValue(!!this.readBits(byteOffset, 1, bitOffset, 1));
+            },
+            encode: function () {
+                this.writeBits(byteOffset, 1, bitOffset, 1, this.instance[name].getValue(false) ? 1 : 0);
+            }
+        };
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'WebSocket opcode=${opcode}',
+            properties: {
+                fin: this.#bitField('fin', 0, 0, 'FIN'),
+                rsv1: this.#bitField('rsv1', 0, 1, 'RSV1'),
+                rsv2: this.#bitField('rsv2', 0, 2, 'RSV2'),
+                rsv3: this.#bitField('rsv3', 0, 3, 'RSV3'),
+                opcode: {
+                    type: 'integer', label: 'Opcode', minimum: 0, maximum: 15,
+                    decode: function () {
+                        this.instance.opcode.setValue(this.readBits(0, 1, 4, 4));
+                    },
+                    encode: function () {
+                        let value = this.instance.opcode.getValue(0);
+                        if (value > 15)
+                            value = 15;
+                        if (value < 0)
+                            value = 0;
+                        this.writeBits(0, 1, 4, 4, value);
+                    }
+                },
+                mask: this.#bitField('mask', 1, 0, 'Mask'),
+                payloadLen: {
+                    type: 'integer', label: 'Payload Length (7-bit)', minimum: 0, maximum: 127,
+                    decode: function () {
+                        this.instance.payloadLen.setValue(this.readBits(1, 1, 1, 7));
+                    },
+                    encode: function () {
+                        let value = this.instance.payloadLen.getValue(0);
+                        if (value > 127)
+                            value = 127;
+                        if (value < 0)
+                            value = 0;
+                        this.writeBits(1, 1, 1, 7, value);
+                    }
+                },
+                //Extended payload length: 2 or 8 bytes (kept verbatim as hex), present per the 7-bit length.
+                extendedPayloadLength: {
+                    type: 'string', label: 'Extended Payload Length', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const bytes = this.#extendedLengthBytes();
+                        this.instance.extendedPayloadLength.setValue(bytes > 0 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(2, bytes)) : '');
+                    },
+                    encode: function () {
+                        const value = this.instance.extendedPayloadLength.getValue('');
+                        if (value)
+                            this.writeBytes(2, (0, HexToBuffer_1.HexToBuffer)(value));
+                    }
+                },
+                //4-byte masking key, present only when MASK is set.
+                maskingKey: {
+                    type: 'string', label: 'Masking Key', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        if (!this.instance.mask.getValue(false))
+                            return;
+                        this.instance.maskingKey.setValue((0, BufferToHex_1.BufferToHex)(this.readBytes(this.#maskOffset(), 4)));
+                    },
+                    encode: function () {
+                        if (!this.instance.mask.getValue(false))
+                            return;
+                        const value = this.instance.maskingKey.getValue('');
+                        if (value)
+                            this.writeBytes(this.#maskOffset(), (0, HexToBuffer_1.HexToBuffer)(value));
+                    }
+                },
+                //The application payload, kept verbatim (masked bytes are NOT unmasked — that would alter
+                //the wire bytes and break the round-trip). Length is the 7-bit length, or the extended
+                //length, bounded by the captured bytes.
+                payload: {
+                    type: 'string', label: 'Payload', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const offset = this.#payloadOffset();
+                        const available = this.packet.length - this.startPos;
+                        const payloadLen = this.instance.payloadLen.getValue(0);
+                        const extended = this.instance.extendedPayloadLength.getValue('');
+                        let length = extended ? parseInt(extended, 16) : payloadLen;
+                        if (!Number.isFinite(length) || length < 0)
+                            length = 0;
+                        if (offset + length > available)
+                            length = available - offset;
+                        if (length < 0)
+                            length = 0;
+                        this.instance.payload.setValue(length > 0 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(offset, length)) : '');
+                    },
+                    encode: function () {
+                        const payload = this.instance.payload.getValue('');
+                        if (payload)
+                            this.writeBytes(this.#payloadOffset(), (0, HexToBuffer_1.HexToBuffer)(payload));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        const prev = this.prevCodecModule;
+        if (!prev || prev.id !== 'tcp')
+            return false;
+        if (this.packet.length - this.startPos < 2)
+            return false;
+        const byte0 = this.readBytes(0, 1, true)[0];
+        //Reserved bits must be 0 (no extension negotiated) and the opcode must be a defined one.
+        if ((byte0 & 0x70) !== 0)
+            return false;
+        const opcode = byte0 & 0x0f;
+        return opcode === 0x0 || opcode === 0x1 || opcode === 0x2 || opcode === 0x8 || opcode === 0x9 || opcode === 0xa;
+    }
+}
+exports.WebSocket = WebSocket;

package/dist/headers/WireGuard.d.ts

@@ -0,0 +1,38 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * WireGuard (the WireGuard protocol, RFC-less / Noise_IKpsk2), UDP — commonly port 51820 but the port is
+ * freely configurable per-peer. Every WireGuard packet opens with a 4-byte prefix: a 1-byte Message Type
+ * (1 = Handshake Initiation, 2 = Handshake Response, 3 = Cookie Reply, 4 = Transport Data) and 3 Reserved
+ * bytes that the spec fixes at zero. The remaining layout is entirely Message-Type-driven:
+ *
+ *   - Type 1 (Handshake Initiation, 148 bytes): sender(4 LE) + ephemeral(32) + static(48) + timestamp(28)
+ *                                               + mac1(16) + mac2(16).
+ *   - Type 2 (Handshake Response, 92 bytes):    sender(4 LE) + receiver(4 LE) + ephemeral(32) + empty(16)
+ *                                               + mac1(16) + mac2(16).
+ *   - Type 3 (Cookie Reply, 64 bytes):          receiver(4 LE) + nonce(24) + cookie(32).
+ *   - Type 4 (Transport Data, variable):        receiver(4 LE) + counter(8 LE) + encryptedPacket(rest).
+ *
+ * ⚠️ The sender / receiver indices are LITTLE-ENDIAN uint32 (WireGuard is little-endian on the wire), and
+ * there is no little-endian helper in this codebase, so they are read/written byte-by-byte in their
+ * closures (`>>> 0` on the WHOLE `|` expression so the high-bit value stays unsigned). The Transport-Data
+ * counter is a 64-bit LE nonce counter; it is kept as an 8-byte HEX field rather than a JS number to
+ * avoid the >2^53 precision loss (and it round-trips its little-endian bytes verbatim). Every crypto blob
+ * (ephemeral/static/timestamp/empty/nonce/cookie/mac1/mac2 and the encrypted payload) is opaque AEAD
+ * output, kept verbatim as HEX. A well-formed packet round-trips byte-for-byte.
+ *
+ * Field presence is branched on Message Type: each field's decode/encode consults a per-type offset table
+ * (`#offsetFor`) and no-ops when the field does not belong to the current type, so the four wire formats
+ * share one schema without phantom bytes.
+ */
+export declare class WireGuard 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/WireGuard.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WireGuard = 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");
+/**
+ * WireGuard (the WireGuard protocol, RFC-less / Noise_IKpsk2), UDP — commonly port 51820 but the port is
+ * freely configurable per-peer. Every WireGuard packet opens with a 4-byte prefix: a 1-byte Message Type
+ * (1 = Handshake Initiation, 2 = Handshake Response, 3 = Cookie Reply, 4 = Transport Data) and 3 Reserved
+ * bytes that the spec fixes at zero. The remaining layout is entirely Message-Type-driven:
+ *
+ *   - Type 1 (Handshake Initiation, 148 bytes): sender(4 LE) + ephemeral(32) + static(48) + timestamp(28)
+ *                                               + mac1(16) + mac2(16).
+ *   - Type 2 (Handshake Response, 92 bytes):    sender(4 LE) + receiver(4 LE) + ephemeral(32) + empty(16)
+ *                                               + mac1(16) + mac2(16).
+ *   - Type 3 (Cookie Reply, 64 bytes):          receiver(4 LE) + nonce(24) + cookie(32).
+ *   - Type 4 (Transport Data, variable):        receiver(4 LE) + counter(8 LE) + encryptedPacket(rest).
+ *
+ * ⚠️ The sender / receiver indices are LITTLE-ENDIAN uint32 (WireGuard is little-endian on the wire), and
+ * there is no little-endian helper in this codebase, so they are read/written byte-by-byte in their
+ * closures (`>>> 0` on the WHOLE `|` expression so the high-bit value stays unsigned). The Transport-Data
+ * counter is a 64-bit LE nonce counter; it is kept as an 8-byte HEX field rather than a JS number to
+ * avoid the >2^53 precision loss (and it round-trips its little-endian bytes verbatim). Every crypto blob
+ * (ephemeral/static/timestamp/empty/nonce/cookie/mac1/mac2 and the encrypted payload) is opaque AEAD
+ * output, kept verbatim as HEX. A well-formed packet round-trips byte-for-byte.
+ *
+ * Field presence is branched on Message Type: each field's decode/encode consults a per-type offset table
+ * (`#offsetFor`) and no-ops when the field does not belong to the current type, so the four wire formats
+ * share one schema without phantom bytes.
+ */
+class WireGuard extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'wireguard';
+        this.name = 'WireGuard';
+        this.nickname = 'WireGuard';
+        this.matchKeys = ['udpport:51820'];
+        //A leaf header — the payload beyond the header is AEAD-encrypted ciphertext with no further structure.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (WireGuard.#schemaCache ??= WireGuard.#buildSchema());
+    }
+    /** Fixed on-wire size of a Message Type with a fixed layout (types 1/2/3); 0 for the variable type 4. */
+    static #FIXED_SIZE = { 1: 148, 2: 92, 3: 64 };
+    /** The WireGuard payload available in this datagram, clamped by the UDP length (drops trailing FCS/padding). */
+    #payloadLength() {
+        let available = this.packet.length - this.startPos;
+        if (this.prevCodecModule && this.prevCodecModule.id === 'udp') {
+            const udpLength = this.prevCodecModule.instance.length.getValue(0);
+            if (udpLength >= 8 && udpLength - 8 < available)
+                available = udpLength - 8;
+        }
+        return available < 0 ? 0 : available;
+    }
+    /**
+     * Header-relative byte offset of `field` for the CURRENT Message Type, or -1 when the field does not
+     * belong to this type. Message Type has been decoded (or, on encode, provided) before any other field
+     * runs — it is the first schema property — so `instance.messageType` is authoritative here.
+     */
+    #offsetFor(field) {
+        const messageType = this.instance.messageType.getValue(0);
+        let layout;
+        switch (messageType) {
+            case 1:
+                layout = { sender: 4, ephemeral: 8, static: 40, timestamp: 88, mac1: 116, mac2: 132 };
+                break;
+            case 2:
+                layout = { sender: 4, receiver: 8, ephemeral: 12, empty: 44, mac1: 60, mac2: 76 };
+                break;
+            case 3:
+                layout = { receiver: 4, nonce: 8, cookie: 32 };
+                break;
+            case 4:
+                layout = { receiver: 4, counter: 8 };
+                break;
+            default: layout = {};
+        }
+        const offset = layout[field];
+        return offset === undefined ? -1 : offset;
+    }
+    /** A little-endian unsigned 32-bit index (sender/receiver) whose offset depends on the Message Type. */
+    static #fieldUInt32LE(name, label) {
+        return {
+            type: 'integer',
+            label: label,
+            minimum: 0,
+            maximum: 4294967295,
+            decode: function () {
+                const offset = this.#offsetFor(name);
+                if (offset < 0)
+                    return;
+                const b = this.readBytes(offset, 4);
+                this.instance[name].setValue((b[0] | (b[1] << 8) | (b[2] << 16) | (b[3] << 24)) >>> 0);
+            },
+            encode: function () {
+                const offset = this.#offsetFor(name);
+                if (offset < 0)
+                    return;
+                const node = this.instance[name];
+                let value = node.getValue(0, (nodePath) => this.recordError(nodePath, 'Not Found'));
+                if (value > 4294967295) {
+                    this.recordError(node.getPath(), 'Maximum value is 4294967295');
+                    value = 4294967295;
+                }
+                if (value < 0) {
+                    this.recordError(node.getPath(), 'Minimum value is 0');
+                    value = 0;
+                }
+                node.setValue(value);
+                this.writeBytes(offset, Buffer.from([value & 0xff, (value >> 8) & 0xff, (value >> 16) & 0xff, (value >>> 24) & 0xff]));
+            }
+        };
+    }
+    /** A fixed-width opaque crypto blob (HEX) whose offset depends on the Message Type. */
+    static #fieldBlob(name, byteLength, label) {
+        const zero = '00'.repeat(byteLength);
+        return {
+            type: 'string',
+            label: label,
+            contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+            decode: function () {
+                const offset = this.#offsetFor(name);
+                if (offset < 0)
+                    return;
+                this.instance[name].setValue((0, BufferToHex_1.BufferToHex)(this.readBytes(offset, byteLength)));
+            },
+            encode: function () {
+                const offset = this.#offsetFor(name);
+                if (offset < 0)
+                    return;
+                this.writeBytes(offset, (0, HexToBuffer_1.HexToBuffer)(this.instance[name].getValue(zero)));
+            }
+        };
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'WireGuard type=${messageType}',
+            properties: {
+                //Message Type first: every other field's presence/offset is branched on it.
+                messageType: this.fieldUInt('messageType', 0, 1, 'Message Type'),
+                //3 Reserved bytes, spec-fixed at zero. Kept as a field (not asserted) so it is visible/editable;
+                //match() requires them zero as part of the content signature, so a non-zero-reserved datagram
+                //is not claimed as WireGuard (it falls to raw) rather than round-tripping through this codec.
+                reserved: this.fieldHex('reserved', 1, 3, 'Reserved'),
+                //Sender index (types 1, 2) — LITTLE-ENDIAN uint32.
+                sender: this.#fieldUInt32LE('sender', 'Sender Index'),
+                //Receiver index (types 2, 3, 4) — LITTLE-ENDIAN uint32.
+                receiver: this.#fieldUInt32LE('receiver', 'Receiver Index'),
+                //Handshake crypto blobs (types 1, 2), all opaque AEAD/Curve25519 output kept verbatim.
+                ephemeral: this.#fieldBlob('ephemeral', 32, 'Unencrypted Ephemeral'),
+                static: this.#fieldBlob('static', 48, 'Encrypted Static'),
+                timestamp: this.#fieldBlob('timestamp', 28, 'Encrypted Timestamp'),
+                empty: this.#fieldBlob('empty', 16, 'Encrypted Empty'),
+                //Cookie Reply blobs (type 3).
+                nonce: this.#fieldBlob('nonce', 24, 'Nonce'),
+                cookie: this.#fieldBlob('cookie', 32, 'Encrypted Cookie'),
+                //Transport Data (type 4): a 64-bit LE counter kept as HEX (avoids >2^53 precision loss) and
+                //the encrypted packet — the rest of the datagram, bounded by the UDP length.
+                counter: this.#fieldBlob('counter', 8, 'Counter'),
+                mac1: this.#fieldBlob('mac1', 16, 'MAC1'),
+                mac2: this.#fieldBlob('mac2', 16, 'MAC2'),
+                encryptedPacket: {
+                    type: 'string',
+                    label: 'Encrypted Packet',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const messageType = this.instance.messageType.getValue(0);
+                        if (messageType !== 4)
+                            return;
+                        const available = this.#payloadLength();
+                        this.instance.encryptedPacket.setValue(available > 16 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(16, available - 16)) : '');
+                    },
+                    encode: function () {
+                        const messageType = this.instance.messageType.getValue(0);
+                        if (messageType !== 4)
+                            return;
+                        const data = this.instance.encryptedPacket.getValue('');
+                        if (data)
+                            this.writeBytes(16, (0, HexToBuffer_1.HexToBuffer)(data));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //WireGuard's port is configurable, so this codec is registered ONLY in the udp/51820 demux bucket
+        //(no heuristicFallback): the 1-byte Message Type + 3 zero Reserved bytes is a weakish 4-byte content
+        //signature that would over-match on arbitrary ports, so the well-known port gates it. Within the
+        //bucket, require Message Type ∈ {1,2,3,4}, the 3 Reserved bytes zero, and the fixed-layout types to
+        //carry their full length — otherwise fall through to raw.
+        if (!this.prevCodecModule || this.prevCodecModule.id !== 'udp')
+            return false;
+        const available = this.#payloadLength();
+        if (available < 4)
+            return false;
+        const messageType = this.readBytes(0, 1, true)[0];
+        if (messageType < 1 || messageType > 4)
+            return false;
+        const reserved = this.readBytes(1, 3, true);
+        if (reserved[0] !== 0 || reserved[1] !== 0 || reserved[2] !== 0)
+            return false;
+        const fixedSize = WireGuard.#FIXED_SIZE[messageType];
+        if (fixedSize !== undefined && available < fixedSize)
+            return false;
+        //Type 4 needs at least the 16-byte transport header (type+reserved+receiver+counter).
+        if (messageType === 4 && available < 16)
+            return false;
+        return true;
+    }
+}
+exports.WireGuard = WireGuard;

package/dist/headers/XMPP.d.ts

@@ -0,0 +1,37 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * XMPP — the Extensible Messaging and Presence Protocol (RFC 6120), the XML-streaming protocol behind
+ * Jabber and many IM/presence systems. It rides over TCP: client-to-server on port 5222, server-to-server
+ * on port 5269. Unlike a request/response protocol, an XMPP session is a pair of open-ended XML streams —
+ * each peer opens a `<stream:stream>` root element and then emits a sequence of "stanzas" (`<message>`,
+ * `<presence>`, `<iq>`) as child elements until the stream is closed with `</stream:stream>`. A single
+ * captured packet therefore carries an arbitrary FRAGMENT of that XML text: the stream preamble
+ * (`<?xml version='1.0'?><stream:stream …>`), one or more whole stanzas, or even a partial element split
+ * across TCP segments.
+ *
+ * Like SIP and HTTP, the payload is text whose full internal structure (namespaces, arbitrary nested
+ * elements, significant whitespace, entity encoding) is far richer than a form needs, and byte ordering /
+ * whitespace is significant to the XML stream parser on the other end. So the ENTIRE raw payload is kept
+ * verbatim as the authoritative `message` field (hex) and re-emitted untouched; only lightweight
+ * display-only metadata (the first element's tag name, whether it is a stream header, whether an XML
+ * declaration is present) is parsed on decode. Encode never reconstructs the XML from the metadata — it
+ * writes `message` back byte-for-byte — so any conformant (or even malformed) XMPP fragment round-trips
+ * exactly.
+ *
+ * Note: XMPP stanzas can span multiple TCP segments and TLS/SASL negotiation (STARTTLS) switches the
+ * stream to ciphertext mid-session; reassembly and post-STARTTLS decryption are out of scope. This
+ * single-segment codec keeps whatever XML bytes are present in the current segment verbatim, which is
+ * byte-perfect for the single-packet case.
+ */
+export declare class XMPP extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}