@netkitty/codec 1.0.0

package/dist/headers/PostgreSQL.d.ts

@@ -0,0 +1,40 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * PostgreSQL frontend/backend protocol, version 3 (the wire protocol of libpq / the `psql` client and the
+ * server), carried over TCP well-known port 5432.
+ *
+ * Almost every message is framed uniformly: a 1-byte ASCII messageType (e.g. 'Q' Query, 'P' Parse, 'R'
+ * Authentication, 'C' CommandComplete, 'D' DataRow, 'Z' ReadyForQuery, 'T' RowDescription, 'S'
+ * ParameterStatus, 'E' ErrorResponse, 'K' BackendKeyData, 'X' Terminate), then a BIG-ENDIAN uint32 length,
+ * then (length − 4) body bytes. Crucially the length INCLUDES its own 4 bytes but NOT the type byte, so a
+ * typed message occupies 1 + length bytes on the wire and its body lives at offset 5.
+ *
+ * ⚠️ EXCEPTION — the very first message of a connection has NO type byte. The StartupMessage (and the
+ * SSLRequest / CancelRequest / GSSENCRequest handshakes) is length(4, BE) + protocol-version-or-code(4) +
+ * params: length still includes its own 4 bytes, so the body (version + params) lives at offset 4, and the
+ * message occupies exactly `length` bytes. The two shapes are told apart by the first byte: a typed
+ * message opens with a printable message-type letter; a startup message opens with the high octet of a
+ * small length (0x00 in practice) and carries a v3 version word (0x0003xxxx) or a special request code at
+ * offset 4. THIS OFFSET DIFFERENCE (typed length@1 body@5 vs startup length@0 body@4) is the crux of the
+ * codec — every field closure branches on it via #isStartupDecode()/#isStartupEncode().
+ *
+ * Per-message-type body structure (Parse's query text + parameter OIDs, DataRow's column array, an
+ * Authentication request's method, …) is message-type-specific and often cross-message (the backend's
+ * reply depends on the frontend's request), so this slice keeps the body verbatim as `body` hex
+ * (byte-perfect), bounded by the length field so a pipelined/trailing message is left to the codec's
+ * recursion / RawData. The length is honored when supplied (a crafted message may lie), else derived as
+ * 4 + body bytes. A well-formed message round-trips byte-for-byte. Structuring per-message-type bodies is
+ * a later slice.
+ */
+export declare class PostgreSQL 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/PostgreSQL.js

@@ -0,0 +1,236 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgreSQL = 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");
+/**
+ * The PostgreSQL v3 message-type bytes (a single ASCII byte that opens every TYPED message). Frontend and
+ * backend share the byte space: e.g. Q Query, P Parse, B Bind, E Execute/ErrorResponse, C Close/
+ * CommandComplete, D Describe/DataRow, R Authentication, Z ReadyForQuery, T RowDescription, S Sync/
+ * ParameterStatus, K BackendKeyData, X Terminate, plus the digit types 1/2/3 (Parse/Bind/CloseComplete).
+ * Used by match() and by decode's typed-vs-startup discriminator — a startup message has NO type byte (see
+ * the class doc), so its first byte is the high octet of a (small) length, never one of these letters.
+ */
+const PG_MESSAGE_TYPES = 'ABCDEFGHIKNPQRSTVWXZcdfnpstvw123';
+/** PostgreSQL v3 protocol-version MAJOR number (the high 16 bits of the startup version word: 0x0003xxxx). */
+const PG_PROTOCOL_MAJOR_V3 = 0x0003;
+/**
+ * The special startup request codes that appear in place of a protocol version: SSLRequest (80877103 =
+ * 0x04d2162f), CancelRequest (80877102 = 0x04d2162e) and GSSENCRequest (80877104 = 0x04d21630). Like a v3
+ * StartupMessage, these have no type byte — length(4) + code(4) [ + payload ].
+ */
+const PG_SPECIAL_REQUEST_CODES = [0x04d2162f, 0x04d2162e, 0x04d21630];
+/**
+ * PostgreSQL frontend/backend protocol, version 3 (the wire protocol of libpq / the `psql` client and the
+ * server), carried over TCP well-known port 5432.
+ *
+ * Almost every message is framed uniformly: a 1-byte ASCII messageType (e.g. 'Q' Query, 'P' Parse, 'R'
+ * Authentication, 'C' CommandComplete, 'D' DataRow, 'Z' ReadyForQuery, 'T' RowDescription, 'S'
+ * ParameterStatus, 'E' ErrorResponse, 'K' BackendKeyData, 'X' Terminate), then a BIG-ENDIAN uint32 length,
+ * then (length − 4) body bytes. Crucially the length INCLUDES its own 4 bytes but NOT the type byte, so a
+ * typed message occupies 1 + length bytes on the wire and its body lives at offset 5.
+ *
+ * ⚠️ EXCEPTION — the very first message of a connection has NO type byte. The StartupMessage (and the
+ * SSLRequest / CancelRequest / GSSENCRequest handshakes) is length(4, BE) + protocol-version-or-code(4) +
+ * params: length still includes its own 4 bytes, so the body (version + params) lives at offset 4, and the
+ * message occupies exactly `length` bytes. The two shapes are told apart by the first byte: a typed
+ * message opens with a printable message-type letter; a startup message opens with the high octet of a
+ * small length (0x00 in practice) and carries a v3 version word (0x0003xxxx) or a special request code at
+ * offset 4. THIS OFFSET DIFFERENCE (typed length@1 body@5 vs startup length@0 body@4) is the crux of the
+ * codec — every field closure branches on it via #isStartupDecode()/#isStartupEncode().
+ *
+ * Per-message-type body structure (Parse's query text + parameter OIDs, DataRow's column array, an
+ * Authentication request's method, …) is message-type-specific and often cross-message (the backend's
+ * reply depends on the frontend's request), so this slice keeps the body verbatim as `body` hex
+ * (byte-perfect), bounded by the length field so a pipelined/trailing message is left to the codec's
+ * recursion / RawData. The length is honored when supplied (a crafted message may lie), else derived as
+ * 4 + body bytes. A well-formed message round-trips byte-for-byte. Structuring per-message-type bodies is
+ * a later slice.
+ */
+class PostgreSQL extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'pgsql';
+        this.name = 'PostgreSQL Protocol';
+        this.nickname = 'PostgreSQL';
+        //PostgreSQL is recognized ONLY on its well-known port bucket 5432 — deliberately NOT via
+        //heuristicFallback. The v3 framing has NO strong global signature: a typed message is just a single
+        //ASCII letter followed by a 4-byte length, and a startup message is a small length followed by a
+        //version word — both are byte patterns that ordinary text or binary streams reproduce constantly, so
+        //(like POP3 and Redis, whose 1-byte/verb signatures are equally weak) joining the global heuristic
+        //chain would let PostgreSQL mis-claim countless non-PG layers on any port. Confining it to the
+        //tcp:5432 bucket makes that impossible off-port; alt-port PostgreSQL is rare and falls losslessly to
+        //raw.
+        this.matchKeys = ['tcpport:5432'];
+        //A leaf header — the per-message-type body requires message-dependent, cross-message parsing.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (_a.#schemaCache ??= _a.#buildSchema());
+    }
+    /** True when `byte` is a printable PostgreSQL v3 message-type byte (opens a TYPED message). */
+    static #isTypeByte(byte) {
+        return PG_MESSAGE_TYPES.includes(String.fromCharCode(byte));
+    }
+    /** Bytes of this header's payload available in the segment (never negative). */
+    #payloadLength() {
+        const available = this.packet.length - this.startPos;
+        return available < 0 ? 0 : available;
+    }
+    /**
+     * Decide, at DECODE time, whether the message at startPos is a startup message (no type byte) vs a
+     * typed message: a typed message opens with a printable message-type letter, so anything else (the
+     * high octet of a small length, 0x00 in practice) is a startup message. match() gates entry to exactly
+     * these two shapes, so this two-way split is reliable.
+     */
+    #isStartupDecode() {
+        if (this.#payloadLength() < 1)
+            return false;
+        return !_a.#isTypeByte(this.readBytes(0, 1, true)[0]);
+    }
+    /**
+     * Decide, at ENCODE time, whether to emit a startup frame (no type byte). The messageType is the
+     * discriminator: a typed message always carries a non-empty type byte, a startup message carries none
+     * (messageType === '', the value decode stores for a startup). So an empty messageType means startup.
+     */
+    #isStartupEncode() {
+        return this.instance.messageType.getValue('') === '';
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'PostgreSQL ${messageType}',
+            properties: {
+                //Display-only flag: is this the type-byte-less startup/handshake message? Set on decode
+                //from the first byte; has no encode of its own (encode derives the framing from
+                //messageType emptiness — see #isStartupEncode), so it never affects the re-emitted bytes.
+                isStartup: {
+                    type: 'boolean',
+                    label: 'Is Startup',
+                    decode: function () {
+                        this.instance.isStartup.setValue(this.#isStartupDecode());
+                    }
+                },
+                //The 1-byte ASCII message type ('' for a startup message, which has no type byte). Decode
+                //reads it only for a typed message; encode writes exactly 1 byte for a typed message and
+                //nothing for a startup message, so both shapes round-trip byte-for-byte.
+                messageType: {
+                    type: 'string',
+                    label: 'Message Type',
+                    maxLength: 1,
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.ASCII,
+                    decode: function () {
+                        this.instance.messageType.setValue(this.#isStartupDecode() ? '' : this.readBytes(0, 1).toString('latin1'));
+                    },
+                    encode: function () {
+                        const value = this.instance.messageType.getValue('');
+                        //Empty ⇒ startup message: no type byte is written (the length is the first field).
+                        if (value === '')
+                            return;
+                        const buffer = Buffer.alloc(1);
+                        Buffer.from(value, 'latin1').copy(buffer, 0, 0, 1);
+                        this.writeBytes(0, buffer);
+                    }
+                },
+                //BIG-ENDIAN uint32 length. It INCLUDES its own 4 bytes but NOT the type byte, so it lives
+                //at offset 1 for a typed message and at offset 0 for a startup message. Honored when
+                //supplied (a crafted message may lie); else derived as 4 (the length word) + body bytes.
+                length: {
+                    type: 'integer',
+                    label: 'Length',
+                    minimum: 0,
+                    maximum: 4294967295,
+                    decode: function () {
+                        const offset = this.#isStartupDecode() ? 0 : 1;
+                        this.instance.length.setValue((0, BufferToNumber_1.BufferToUInt32)(this.readBytes(offset, 4)));
+                    },
+                    encode: function () {
+                        const startup = this.#isStartupEncode();
+                        const provided = this.instance.length.getValue();
+                        let value = (provided !== undefined && provided !== null)
+                            ? provided
+                            : 4 + (0, HexToBuffer_1.HexToBuffer)(this.instance.body.getValue('')).length;
+                        if (value > 4294967295) {
+                            this.recordError(this.instance.length.getPath(), 'Maximum value is 4294967295');
+                            value = 4294967295;
+                        }
+                        if (value < 0) {
+                            this.recordError(this.instance.length.getPath(), 'Minimum value is 0');
+                            value = 0;
+                        }
+                        this.instance.length.setValue(value);
+                        this.writeBytes(startup ? 0 : 1, (0, NumberToBuffer_1.UInt32ToBuffer)(value));
+                    }
+                },
+                //The message body after the length word, kept verbatim. For a TYPED message the body is at
+                //offset 5 (type byte + 4 length bytes) and the message ends at 1 + length; for a STARTUP
+                //message the body (version/code + params) is at offset 4 and the message ends at length.
+                //Bounded by the length field and the captured bytes, so trailing/pipelined data is left to
+                //the codec's recursion / RawData.
+                body: {
+                    type: 'string',
+                    label: 'Body',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const remaining = this.#payloadLength();
+                        const startup = this.#isStartupDecode();
+                        const headerLen = startup ? 4 : 5;
+                        const length = this.instance.length.getValue(0);
+                        //Wire span of the whole message: startup = length; typed = 1 (type) + length.
+                        let end = startup ? length : 1 + length;
+                        if (end > remaining)
+                            end = remaining;
+                        if (end < headerLen)
+                            end = headerLen;
+                        this.instance.body.setValue(end > headerLen ? (0, BufferToHex_1.BufferToHex)(this.readBytes(headerLen, end - headerLen)) : '');
+                    },
+                    encode: function () {
+                        const headerLen = this.#isStartupEncode() ? 4 : 5;
+                        const body = this.instance.body.getValue('');
+                        if (body)
+                            this.writeBytes(headerLen, (0, HexToBuffer_1.HexToBuffer)(body));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //PostgreSQL rides on TCP port 5432. Within that bucket, confirm one of the two v3 shapes so
+        //non-PG traffic on 5432 falls through to raw:
+        //  • a TYPED message — a known message-type letter followed by a plausible 4-byte length; or
+        //  • a STARTUP message — a small length (8..296) whose next 4 bytes are a v3 version word
+        //    (0x0003xxxx) or a special request code (SSLRequest / CancelRequest / GSSENCRequest).
+        if (!this.prevCodecModule || this.prevCodecModule.id !== 'tcp')
+            return false;
+        //Need at least a type byte + a 4-byte length (typed), which is also enough for a startup's
+        //length + the start of its version word.
+        if (this.#payloadLength() < 5)
+            return false;
+        const first = this.readBytes(0, 1, true)[0];
+        if (_a.#isTypeByte(first)) {
+            //Typed message: length includes its own 4 bytes, so a sane length is >= 4 and not absurd
+            //(PostgreSQL caps a message at ~1 GiB).
+            const length = (0, BufferToNumber_1.BufferToUInt32)(this.readBytes(1, 4, true));
+            return length >= 4 && length <= 0x3fffffff;
+        }
+        //Startup message: length(4) + version-or-code(4). Require the full 8 bytes and a plausible,
+        //bounded length, then a v3 version word or a recognized special request code.
+        if (this.#payloadLength() < 8)
+            return false;
+        const length = (0, BufferToNumber_1.BufferToUInt32)(this.readBytes(0, 4, true));
+        if (length < 8 || length > 296)
+            return false;
+        const code = (0, BufferToNumber_1.BufferToUInt32)(this.readBytes(4, 4, true));
+        if ((code >>> 16) === PG_PROTOCOL_MAJOR_V3)
+            return true;
+        return PG_SPECIAL_REQUEST_CODES.includes(code);
+    }
+}
+exports.PostgreSQL = PostgreSQL;
+_a = PostgreSQL;

package/dist/headers/QUIC.d.ts

@@ -0,0 +1,34 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * QUIC — the UDP-based multiplexed and secure transport (RFC 9000), the substrate under HTTP/3. Every
+ * QUIC packet begins with a first byte whose most-significant bit is the Header Form: 1 = Long Header
+ * (used during connection setup — Initial / 0-RTT / Handshake / Retry / Version Negotiation), 0 = Short
+ * Header (1-RTT, used once the connection is established). This header structures the LONG header only:
+ *
+ *   first byte  = Header Form(1) | Fixed Bit(1) | Long Packet Type(2) | type-specific(4)
+ *   Version(4) | DCID Len(1) | DCID(DCID Len) | SCID Len(1) | SCID(SCID Len) | ...rest
+ *
+ * Everything after the Source Connection ID (token / length / packet number / frames) is protected by
+ * QUIC header protection + AEAD encryption, so it is kept verbatim as an opaque `payload` hex (bounded
+ * by the UDP payload) — this is a best-effort structural slice, not a decryptor. The one exception is
+ * Version Negotiation (Version == 0, RFC 9000 §17.2.1): its body is an unencrypted list of 4-byte
+ * Supported Versions, decoded into `supportedVersions`.
+ *
+ * The Short Header (MSB clear) is deliberately NOT recognized by the content heuristic — its first byte
+ * is an almost signature-free value, so heuristic matching would over-claim ordinary UDP traffic; it is
+ * left to later enrichment / RawData. The connection-ID length fields are honored when supplied else
+ * derived from the ID bytes; the type-specific bits and all opaque bytes round-trip byte-for-byte.
+ */
+export declare class QUIC 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/QUIC.js

@@ -0,0 +1,308 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUIC = 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");
+/**
+ * QUIC — the UDP-based multiplexed and secure transport (RFC 9000), the substrate under HTTP/3. Every
+ * QUIC packet begins with a first byte whose most-significant bit is the Header Form: 1 = Long Header
+ * (used during connection setup — Initial / 0-RTT / Handshake / Retry / Version Negotiation), 0 = Short
+ * Header (1-RTT, used once the connection is established). This header structures the LONG header only:
+ *
+ *   first byte  = Header Form(1) | Fixed Bit(1) | Long Packet Type(2) | type-specific(4)
+ *   Version(4) | DCID Len(1) | DCID(DCID Len) | SCID Len(1) | SCID(SCID Len) | ...rest
+ *
+ * Everything after the Source Connection ID (token / length / packet number / frames) is protected by
+ * QUIC header protection + AEAD encryption, so it is kept verbatim as an opaque `payload` hex (bounded
+ * by the UDP payload) — this is a best-effort structural slice, not a decryptor. The one exception is
+ * Version Negotiation (Version == 0, RFC 9000 §17.2.1): its body is an unencrypted list of 4-byte
+ * Supported Versions, decoded into `supportedVersions`.
+ *
+ * The Short Header (MSB clear) is deliberately NOT recognized by the content heuristic — its first byte
+ * is an almost signature-free value, so heuristic matching would over-claim ordinary UDP traffic; it is
+ * left to later enrichment / RawData. The connection-ID length fields are honored when supplied else
+ * derived from the ID bytes; the type-specific bits and all opaque bytes round-trip byte-for-byte.
+ */
+class QUIC extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'quic';
+        this.name = 'QUIC Transport';
+        this.nickname = 'QUIC';
+        //Bucketed on the common HTTP/3 port; heuristicFallback keeps it recognized on any other UDP port via
+        //its long-header + known-version signature (QUIC is used on many ports).
+        this.matchKeys = ['udpport:443'];
+        this.heuristicFallback = true;
+        //A leaf header — the payload is AEAD-encrypted and kept verbatim (no inner demux).
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (QUIC.#schemaCache ??= QUIC.#buildSchema());
+    }
+    /**
+     * Bytes available to this QUIC packet, bounded by the enclosing UDP payload (udp.length - 8) so a
+     * lying connection-ID length near the end of the datagram cannot read into trailing bytes, and so the
+     * opaque payload stops at the datagram boundary rather than swallowing the whole captured buffer.
+     */
+    #available() {
+        let available = this.packet.length - this.startPos;
+        const prev = this.prevCodecModule;
+        if (prev && prev.id === 'udp') {
+            const udpPayload = prev.instance.length.getValue(0) - 8;
+            if (udpPayload >= 0 && udpPayload < available)
+                available = udpPayload;
+        }
+        return available < 0 ? 0 : available;
+    }
+    /** Absolute (header-relative) offset of the SCID Length octet = 6 + DCID Len. */
+    #scidLengthOffset() {
+        return 6 + this.instance.dcidLength.getValue(0);
+    }
+    /** Absolute (header-relative) offset of the bytes following the SCID = 7 + DCID Len + SCID Len. */
+    #tailOffset() {
+        return 7 + this.instance.dcidLength.getValue(0) + this.instance.scidLength.getValue(0);
+    }
+    /** A single flag bit within the first byte (bit 0 = MSB). */
+    static #flagBit(name, bitOffset, label) {
+        return {
+            type: 'boolean',
+            label: label,
+            decode: function () {
+                this.instance.firstByte[name].setValue(!!this.readBits(0, 1, bitOffset, 1));
+            },
+            encode: function () {
+                const value = !!this.instance.firstByte[name].getValue();
+                this.instance.firstByte[name].setValue(value);
+                this.writeBits(0, 1, bitOffset, 1, value ? 1 : 0);
+            }
+        };
+    }
+    /** An unsigned integer packed into `bitLength` bits of the first byte at `bitOffset` (MSB-first). */
+    static #uintBits(name, bitOffset, bitLength, label) {
+        const maximum = (1 << bitLength) - 1;
+        return {
+            type: 'integer',
+            label: label,
+            minimum: 0,
+            maximum: maximum,
+            decode: function () {
+                this.instance.firstByte[name].setValue(this.readBits(0, 1, bitOffset, bitLength));
+            },
+            encode: function () {
+                const node = this.instance.firstByte[name];
+                let value = node.getValue(0);
+                if (value > maximum)
+                    value = maximum;
+                if (value < 0)
+                    value = 0;
+                node.setValue(value);
+                this.writeBits(0, 1, bitOffset, bitLength, value);
+            }
+        };
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'QUIC v=${version} type=${firstByte.longPacketType}',
+            properties: {
+                //First byte: Header Form(bit0) | Fixed Bit(bit1) | Long Packet Type(bits2-3) |
+                //type-specific(bits4-7). For Initial/0-RTT/Handshake the low 4 bits are Reserved(2) +
+                //Packet Number Length(2) but they are masked by header protection on the wire, so they are
+                //kept verbatim as a single opaque 4-bit field (Retry has no such split).
+                firstByte: {
+                    type: 'object',
+                    label: 'First Byte',
+                    properties: {
+                        headerForm: this.#flagBit('headerForm', 0, 'Header Form (1=Long)'),
+                        fixedBit: this.#flagBit('fixedBit', 1, 'Fixed Bit'),
+                        longPacketType: this.#uintBits('longPacketType', 2, 2, 'Long Packet Type'),
+                        typeSpecificBits: this.#uintBits('typeSpecificBits', 4, 4, 'Type-Specific Bits')
+                    }
+                },
+                //Version — 0x00000001 = QUIC v1 (RFC 9000), 0x6b3343cf = v2 (RFC 9369), 0xff0000xx = IETF
+                //drafts, 0x00000000 = Version Negotiation. Kept as a lower-case hex string so any value
+                //round-trips verbatim and the field is unbounded (the match gate restricts real selection).
+                version: this.fieldHex('version', 1, 4, 'Version'),
+                //Destination Connection ID length (0..20 per RFC 9000, but any 0..255 round-trips). Honored
+                //when supplied, else derived from the DCID bytes.
+                dcidLength: {
+                    type: 'integer',
+                    label: 'DCID Length',
+                    minimum: 0,
+                    maximum: 255,
+                    decode: function () {
+                        this.instance.dcidLength.setValue((0, BufferToNumber_1.BufferToUInt8)(this.readBytes(5, 1)));
+                    },
+                    encode: function () {
+                        const provided = this.instance.dcidLength.getValue();
+                        let value = (provided !== undefined && provided !== null)
+                            ? provided
+                            : (0, HexToBuffer_1.HexToBuffer)(this.instance.dcid.getValue('')).length;
+                        if (value > 255)
+                            value = 255;
+                        if (value < 0)
+                            value = 0;
+                        this.instance.dcidLength.setValue(value);
+                        this.writeBytes(5, (0, NumberToBuffer_1.UInt8ToBuffer)(value));
+                    }
+                },
+                //Destination Connection ID, kept verbatim. Bounded by DCID Len and the UDP payload.
+                dcid: {
+                    type: 'string',
+                    label: 'Destination Connection ID',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const dcidLength = this.instance.dcidLength.getValue(0);
+                        this.instance.dcid.setValue(dcidLength > 0 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(6, dcidLength)) : '');
+                    },
+                    encode: function () {
+                        const dcid = this.instance.dcid.getValue('');
+                        if (dcid)
+                            this.writeBytes(6, (0, HexToBuffer_1.HexToBuffer)(dcid));
+                    }
+                },
+                //Source Connection ID length. Offset is dynamic (after the DCID). Honored else derived.
+                scidLength: {
+                    type: 'integer',
+                    label: 'SCID Length',
+                    minimum: 0,
+                    maximum: 255,
+                    decode: function () {
+                        this.instance.scidLength.setValue((0, BufferToNumber_1.BufferToUInt8)(this.readBytes(this.#scidLengthOffset(), 1)));
+                    },
+                    encode: function () {
+                        const provided = this.instance.scidLength.getValue();
+                        let value = (provided !== undefined && provided !== null)
+                            ? provided
+                            : (0, HexToBuffer_1.HexToBuffer)(this.instance.scid.getValue('')).length;
+                        if (value > 255)
+                            value = 255;
+                        if (value < 0)
+                            value = 0;
+                        this.instance.scidLength.setValue(value);
+                        this.writeBytes(this.#scidLengthOffset(), (0, NumberToBuffer_1.UInt8ToBuffer)(value));
+                    }
+                },
+                //Source Connection ID, kept verbatim. Offset is dynamic (after the SCID Length octet).
+                scid: {
+                    type: 'string',
+                    label: 'Source Connection ID',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const scidLength = this.instance.scidLength.getValue(0);
+                        const offset = this.#scidLengthOffset() + 1;
+                        this.instance.scid.setValue(scidLength > 0 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(offset, scidLength)) : '');
+                    },
+                    encode: function () {
+                        const scid = this.instance.scid.getValue('');
+                        if (scid)
+                            this.writeBytes(this.#scidLengthOffset() + 1, (0, HexToBuffer_1.HexToBuffer)(scid));
+                    }
+                },
+                //Version Negotiation only (Version == 0): an unencrypted list of 4-byte Supported Versions
+                //(RFC 9000 §17.2.1). Empty for every other packet type — mutually exclusive with `payload`.
+                supportedVersions: {
+                    type: 'array',
+                    label: 'Supported Versions',
+                    items: {
+                        type: 'string',
+                        label: 'Version',
+                        contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX
+                    },
+                    decode: function () {
+                        const version = this.instance.version.getValue('');
+                        if (version !== '00000000') {
+                            this.instance.supportedVersions.setValue([]);
+                            return;
+                        }
+                        const available = this.#available();
+                        const versions = [];
+                        let offset = this.#tailOffset();
+                        //Each Supported Version is exactly 4 bytes; stop at the datagram boundary. offset
+                        //advances by 4 each turn so the loop always terminates.
+                        while (offset + 4 <= available) {
+                            versions.push((0, BufferToHex_1.BufferToHex)(this.readBytes(offset, 4)));
+                            offset += 4;
+                        }
+                        this.instance.supportedVersions.setValue(versions);
+                    },
+                    encode: function () {
+                        const version = this.instance.version.getValue('');
+                        if (version !== '00000000')
+                            return;
+                        const versions = this.instance.supportedVersions.getValue();
+                        if (!versions)
+                            return;
+                        let offset = this.#tailOffset();
+                        versions.forEach((version) => {
+                            //Each entry is sized to 4 bytes: extra dropped, short zero-padded — a
+                            //Supported Version is a fixed 32-bit value.
+                            this.writeBytes(offset, (0, HexToBuffer_1.HexToBuffer)(version ? version : '', 4));
+                            offset += 4;
+                        });
+                    }
+                },
+                //Everything after the SCID for a normal (non-VN) packet: token / length / packet number /
+                //encrypted frames — kept verbatim (AEAD + header protection, not decryptable here).
+                //Bounded by the UDP payload so a trailing datagram is left to the codec's recursion.
+                payload: {
+                    type: 'string',
+                    label: 'Payload',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const version = this.instance.version.getValue('');
+                        if (version === '00000000') {
+                            this.instance.payload.setValue('');
+                            return;
+                        }
+                        const available = this.#available();
+                        const offset = this.#tailOffset();
+                        this.instance.payload.setValue(offset < available ? (0, BufferToHex_1.BufferToHex)(this.readBytes(offset, available - offset)) : '');
+                    },
+                    encode: function () {
+                        const version = this.instance.version.getValue('');
+                        if (version === '00000000')
+                            return;
+                        const payload = this.instance.payload.getValue('');
+                        if (payload)
+                            this.writeBytes(this.#tailOffset(), (0, HexToBuffer_1.HexToBuffer)(payload));
+                    }
+                }
+            }
+        };
+    }
+    /** True when the enclosing UDP source or destination port is the well-known QUIC port. */
+    #onQuicPort() {
+        const prev = this.prevCodecModule;
+        return prev.instance.srcport.getValue(0) === 443 || prev.instance.dstport.getValue(0) === 443;
+    }
+    match() {
+        //QUIC rides UDP. Require the minimal long header (first byte + version + two length octets = 7
+        //bytes) within the UDP payload, the Long Header form bit set, and — the strong part — a KNOWN
+        //QUIC version. Short headers (MSB clear) and unknown versions are NOT heuristically claimed, so
+        //ordinary UDP traffic falls through to raw. Version Negotiation (version 0) is a weak signature,
+        //so it is only accepted on the well-known QUIC port bucket, never off-port via the heuristic.
+        if (!this.prevCodecModule || this.prevCodecModule.id !== 'udp')
+            return false;
+        if (this.#available() < 7)
+            return false;
+        if ((this.readBytes(0, 1, true)[0] & 0x80) === 0)
+            return false;
+        const version = (0, BufferToNumber_1.BufferToUInt32)(this.readBytes(1, 4, true));
+        if (version === 0x00000001)
+            return true;
+        if (version === 0x6b3343cf)
+            return true;
+        if ((version >>> 8) === 0xff0000)
+            return true;
+        if (version === 0)
+            return this.#onQuicPort();
+        return false;
+    }
+}
+exports.QUIC = QUIC;

package/dist/headers/RADIUS.d.ts

@@ -0,0 +1,24 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * RADIUS — Remote Authentication Dial-In User Service (RFC 2865 auth / RFC 2866 accounting), UDP ports
+ * 1812 (auth) and 1813 (accounting). A 20-byte fixed header — Code, Identifier, Length (the whole
+ * packet), and a 16-byte Authenticator — followed by attributes (AVPs) in Type-Length-Value form:
+ * type(1) + length(1, counts the type+length+value) + value(length-2).
+ *
+ * Attributes are carried generically (type + verbatim hex value) so every attribute — including
+ * Vendor-Specific (26) whose value nests sub-AVPs — round-trips byte-for-byte; per-attribute semantic
+ * decoding is a later enrichment. The AVP walk is bounded by the RADIUS Length (and the UDP payload),
+ * so any trailing padding/FCS spills to the raw layer.
+ */
+export declare class RADIUS extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}