@netkitty/codec 1.0.0

package/dist/headers/TFTP.d.ts

@@ -0,0 +1,28 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * TFTP — Trivial File Transfer Protocol (RFC 1350, options RFC 2347). Each message starts with a
+ * 2-byte opcode: RRQ(1)/WRQ(2) = filename + mode (both null-terminated) + optional name/value options;
+ * DATA(3) = block-number(2) + data; ACK(4) = block-number(2); ERROR(5) = error-code(2) + message
+ * (null-terminated); OACK(6) = name/value options.
+ *
+ * Only the initial RRQ/WRQ rides the well-known UDP port 69; the ensuing DATA/ACK transfer moves to a
+ * server-chosen ephemeral port (a TID), so those packets are a stateful conversation that belongs to
+ * the reassembly/conversation layer, not this single-packet, port-69 codec. The codec decodes every
+ * opcode structurally (so a DATA/ACK reached by other means still parses), but demux only claims
+ * port-69 traffic. Strings are kept verbatim (latin1) and re-emitted with their null terminator; DATA
+ * payload is kept as raw hex — so a well-formed message round-trips byte-for-byte. (A truncated string
+ * missing its RFC-mandated null terminator is malformed: it decodes best-effort but re-emits with the
+ * terminator, so it is not byte-perfect — the byte-perfect guarantee is for standard-conformant TFTP.)
+ */
+export declare class TFTP 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/TFTP.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TFTP = 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");
+/**
+ * TFTP — Trivial File Transfer Protocol (RFC 1350, options RFC 2347). Each message starts with a
+ * 2-byte opcode: RRQ(1)/WRQ(2) = filename + mode (both null-terminated) + optional name/value options;
+ * DATA(3) = block-number(2) + data; ACK(4) = block-number(2); ERROR(5) = error-code(2) + message
+ * (null-terminated); OACK(6) = name/value options.
+ *
+ * Only the initial RRQ/WRQ rides the well-known UDP port 69; the ensuing DATA/ACK transfer moves to a
+ * server-chosen ephemeral port (a TID), so those packets are a stateful conversation that belongs to
+ * the reassembly/conversation layer, not this single-packet, port-69 codec. The codec decodes every
+ * opcode structurally (so a DATA/ACK reached by other means still parses), but demux only claims
+ * port-69 traffic. Strings are kept verbatim (latin1) and re-emitted with their null terminator; DATA
+ * payload is kept as raw hex — so a well-formed message round-trips byte-for-byte. (A truncated string
+ * missing its RFC-mandated null terminator is malformed: it decodes best-effort but re-emits with the
+ * terminator, so it is not byte-perfect — the byte-perfect guarantee is for standard-conformant TFTP.)
+ */
+class TFTP extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'tftp';
+        this.name = 'Trivial File Transfer Protocol';
+        this.nickname = 'TFTP';
+        //Only the initial RRQ/WRQ uses the well-known port 69; the DATA/ACK transfer moves to an ephemeral
+        //TID (a stateful conversation for the reassembly layer), so demux claims port 69 only.
+        this.matchKeys = ['udpport:69'];
+        //A leaf header — nothing demuxes above TFTP.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (TFTP.#schemaCache ??= TFTP.#buildSchema());
+    }
+    /** The payload length bounded by the UDP datagram (so a retained FCS/padding is not absorbed). */
+    #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;
+    }
+    /** Read a null-terminated string at `offset` (bounded by `available`); returns it plus the offset past the terminator. */
+    #readCString(offset, available) {
+        let p = offset;
+        while (p < available && this.readBytes(p, 1, true)[0] !== 0)
+            p++;
+        const value = p > offset ? this.readBytes(offset, p - offset).toString('latin1') : '';
+        let next = p;
+        if (p < available) {
+            this.readBytes(p, 1); //consume the null terminator (extends headerLength)
+            next = p + 1;
+        }
+        return { value: value, next: next };
+    }
+    /** Read a run of null-terminated name/value option pairs from `offset` to `available`. */
+    #readOptions(offset, available) {
+        const options = [];
+        let o = offset;
+        while (o < available) {
+            const name = this.#readCString(o, available);
+            if (name.next >= available && name.value === '')
+                break;
+            const value = this.#readCString(name.next, available);
+            options.push({ name: name.value, value: value.value });
+            o = value.next;
+        }
+        return { options: options, next: o };
+    }
+    #writeCString(offset, value) {
+        const bytes = Buffer.from(value ? value : '', 'latin1');
+        this.writeBytes(offset, bytes);
+        this.writeBytes(offset + bytes.length, Buffer.from([0]));
+        return offset + bytes.length + 1;
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'TFTP opcode=${opcode}',
+            properties: {
+                //Opcode-driven layout, so the whole message is parsed/emitted here; the fields below
+                //carry only schema metadata and are populated per opcode.
+                opcode: {
+                    type: 'integer',
+                    label: 'Opcode',
+                    minimum: 0,
+                    maximum: 65535,
+                    decode: function () {
+                        const available = this.#payloadLength();
+                        if (available < 2) {
+                            //Too short to hold even the 2-byte opcode. match() already prevents claiming
+                            //such a payload; seed a valid (schema-shaped) instance defensively so the
+                            //decode result is always re-encodable (never an undefined-data layer).
+                            this.instance.opcode.setValue(0);
+                            return;
+                        }
+                        const opcode = (0, BufferToNumber_1.BufferToUInt16)(this.readBytes(0, 2));
+                        this.instance.opcode.setValue(opcode);
+                        let offset = 2;
+                        switch (opcode) {
+                            case 1:
+                            case 2: {
+                                const filename = this.#readCString(offset, available);
+                                const mode = this.#readCString(filename.next, available);
+                                this.instance.filename.setValue(filename.value);
+                                this.instance.mode.setValue(mode.value);
+                                this.instance.options.setValue(this.#readOptions(mode.next, available).options);
+                                break;
+                            }
+                            case 3: {
+                                this.instance.block.setValue(available >= 4 ? (0, BufferToNumber_1.BufferToUInt16)(this.readBytes(offset, 2)) : 0);
+                                offset += 2;
+                                this.instance.data.setValue(offset < available ? (0, BufferToHex_1.BufferToHex)(this.readBytes(offset, available - offset)) : '');
+                                break;
+                            }
+                            case 4: {
+                                this.instance.block.setValue(available >= 4 ? (0, BufferToNumber_1.BufferToUInt16)(this.readBytes(offset, 2)) : 0);
+                                break;
+                            }
+                            case 5: {
+                                this.instance.errorCode.setValue(available >= 4 ? (0, BufferToNumber_1.BufferToUInt16)(this.readBytes(offset, 2)) : 0);
+                                offset += 2;
+                                this.instance.errorMessage.setValue(this.#readCString(offset, available).value);
+                                break;
+                            }
+                            case 6: {
+                                this.instance.options.setValue(this.#readOptions(offset, available).options);
+                                break;
+                            }
+                            default: {
+                                //Unknown opcode: keep the body verbatim for a byte-perfect round-trip.
+                                this.instance.rawBody.setValue(offset < available ? (0, BufferToHex_1.BufferToHex)(this.readBytes(offset, available - offset)) : '');
+                            }
+                        }
+                    },
+                    encode: function () {
+                        const opcode = this.instance.opcode.getValue(0);
+                        this.writeBytes(0, (0, NumberToBuffer_1.UInt16ToBuffer)(opcode));
+                        let offset = 2;
+                        switch (opcode) {
+                            case 1:
+                            case 2: {
+                                offset = this.#writeCString(offset, this.instance.filename.getValue(''));
+                                offset = this.#writeCString(offset, this.instance.mode.getValue(''));
+                                const options = this.instance.options.getValue([]);
+                                if (options)
+                                    for (const option of options) {
+                                        offset = this.#writeCString(offset, option.name ? option.name : '');
+                                        offset = this.#writeCString(offset, option.value ? option.value : '');
+                                    }
+                                break;
+                            }
+                            case 3: {
+                                this.writeBytes(offset, (0, NumberToBuffer_1.UInt16ToBuffer)(this.instance.block.getValue(0)));
+                                offset += 2;
+                                const data = (0, HexToBuffer_1.HexToBuffer)(this.instance.data.getValue(''));
+                                if (data.length)
+                                    this.writeBytes(offset, data);
+                                break;
+                            }
+                            case 4: {
+                                this.writeBytes(offset, (0, NumberToBuffer_1.UInt16ToBuffer)(this.instance.block.getValue(0)));
+                                break;
+                            }
+                            case 5: {
+                                this.writeBytes(offset, (0, NumberToBuffer_1.UInt16ToBuffer)(this.instance.errorCode.getValue(0)));
+                                offset += 2;
+                                this.#writeCString(offset, this.instance.errorMessage.getValue(''));
+                                break;
+                            }
+                            case 6: {
+                                const options = this.instance.options.getValue([]);
+                                if (options)
+                                    for (const option of options) {
+                                        offset = this.#writeCString(offset, option.name ? option.name : '');
+                                        offset = this.#writeCString(offset, option.value ? option.value : '');
+                                    }
+                                break;
+                            }
+                            default: {
+                                const rawBody = this.instance.rawBody.getValue('');
+                                if (rawBody)
+                                    this.writeBytes(offset, (0, HexToBuffer_1.HexToBuffer)(rawBody));
+                            }
+                        }
+                    }
+                },
+                filename: { type: 'string', label: 'File Name' },
+                mode: { type: 'string', label: 'Mode' },
+                block: { type: 'integer', label: 'Block Number', minimum: 0, maximum: 65535 },
+                errorCode: { type: 'integer', label: 'Error Code', minimum: 0, maximum: 65535 },
+                errorMessage: { type: 'string', label: 'Error Message' },
+                data: { type: 'string', label: 'Data', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX },
+                options: {
+                    type: 'array',
+                    label: 'Options',
+                    items: {
+                        type: 'object',
+                        label: 'Option',
+                        properties: {
+                            name: { type: 'string', label: 'Name' },
+                            value: { type: 'string', label: 'Value' }
+                        }
+                    }
+                },
+                rawBody: { type: 'string', label: 'Body', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX, hidden: true }
+            }
+        };
+    }
+    match() {
+        //Require at least the 2-byte opcode within the UDP payload — a shorter datagram on port 69 is
+        //not a TFTP message and must fall through to raw (rather than claim an un-decodable layer).
+        return !!this.prevCodecModule && this.prevCodecModule.id === 'udp' && this.#payloadLength() >= 2;
+    }
+}
+exports.TFTP = TFTP;

package/dist/headers/TLS_Alert.d.ts

@@ -0,0 +1,24 @@
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { BaseHeader } from '../abstracts/BaseHeader';
+/**
+ * TLS Alert protocol — a TLS/SSL record carrying an alert, over TCP (heuristically, port 443). This codec
+ * decodes the 5-octet TLS record header followed by the 2-octet alert body: an 8-bit Content Type
+ * (`contentType`, offset 0, = 21 for Alert), a 16-bit legacy Version (`version`, offset 1, mapped to the
+ * labels SSL3.0 / TLS1.0 / TLS1.1 / TLS1.2 / TLS1.3 for 0x0300-0x0304, else "0"), a 16-bit record Length
+ * (`length`, offset 3), then the AlertLevel (`levelType`, offset 5; 1 Warning, 2 Fatal, else the numeric
+ * value) and the AlertDescription (`descriptionType`, offset 6; mapped to a named string for each defined
+ * code — Close notify, Handshake failure, Bad certificate, … — else the numeric value).
+ *
+ * The Version, level and description are decoded to friendly labels and re-encoded back to their numeric
+ * on-wire form, so a well-formed alert round-trips. In the heuristic chain (`heuristicFallback`), match()
+ * requires a Content Type of 21 and a recognized legacy Version (0x0300-0x0304).
+ */
+export declare class TLS_Alert extends BaseHeader {
+    SCHEMA: ProtocolJSONSchema;
+    id: string;
+    readonly matchKeys: string[];
+    readonly heuristicFallback: boolean;
+    name: string;
+    nickname: string;
+    match(): boolean;
+}