@netkitty/codec 1.0.0

package/dist/headers/SNMP.d.ts

@@ -0,0 +1,28 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * SNMP — Simple Network Management Protocol v1 / v2c (RFC 1157 / RFC 3416). The message is a single
+ * ASN.1 BER structure: SEQUENCE { version INTEGER, community OCTET STRING, PDU }, where the PDU is a
+ * context tag ([0]=get-request … [2]=get-response/response, [3]=set-request, [5]=get-bulk-request,
+ * [7]=snmpV2-trap …) wrapping SEQUENCE { request-id, error-status, error-index, variable-bindings }.
+ * Rides UDP ports 161 (agent) and 162 (trap).
+ *
+ * Byte-perfect strategy: the four INTEGER fields are decoded as signed integers and re-emitted with
+ * minimal two's-complement BER; the object identifier is decoded to a dotted string and re-emitted via
+ * base-128 sub-identifiers; community is kept as a latin1 string; and each binding's VALUE is kept as
+ * its BER tag + verbatim hex content (so any value type — OctetString, TimeTicks, Counter, IpAddress,
+ * Null … — round-trips exactly without needing a per-type encoder). Definite lengths are re-derived in
+ * minimal form, matching the standard DER-style encoding SNMP agents emit. SNMPv3 (which adds security
+ * parameters and optional encryption) is a later, separate concern.
+ */
+export declare class SNMP 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/SNMP.js

@@ -0,0 +1,302 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SNMP = void 0;
+const BaseHeader_1 = require("../abstracts/BaseHeader");
+const StringContentEncodingEnum_1 = require("../lib/StringContentEncodingEnum");
+/**
+ * SNMP — Simple Network Management Protocol v1 / v2c (RFC 1157 / RFC 3416). The message is a single
+ * ASN.1 BER structure: SEQUENCE { version INTEGER, community OCTET STRING, PDU }, where the PDU is a
+ * context tag ([0]=get-request … [2]=get-response/response, [3]=set-request, [5]=get-bulk-request,
+ * [7]=snmpV2-trap …) wrapping SEQUENCE { request-id, error-status, error-index, variable-bindings }.
+ * Rides UDP ports 161 (agent) and 162 (trap).
+ *
+ * Byte-perfect strategy: the four INTEGER fields are decoded as signed integers and re-emitted with
+ * minimal two's-complement BER; the object identifier is decoded to a dotted string and re-emitted via
+ * base-128 sub-identifiers; community is kept as a latin1 string; and each binding's VALUE is kept as
+ * its BER tag + verbatim hex content (so any value type — OctetString, TimeTicks, Counter, IpAddress,
+ * Null … — round-trips exactly without needing a per-type encoder). Definite lengths are re-derived in
+ * minimal form, matching the standard DER-style encoding SNMP agents emit. SNMPv3 (which adds security
+ * parameters and optional encryption) is a later, separate concern.
+ */
+class SNMP extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'snmp';
+        this.name = 'Simple Network Management Protocol';
+        this.nickname = 'SNMP';
+        //Agent port 161, trap/notification port 162 (both UDP). BER SEQUENCE has no reliable content
+        //signature, so this is port-defined (no heuristicFallback).
+        this.matchKeys = ['udpport:161', 'udpport:162'];
+        //A leaf header — nothing demuxes above SNMP.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    //The PDU tags that share the RFC 3416 body shape {request-id, error-status, error-index, varbinds}:
+    //get-request(0xa0), get-next(0xa1), get-response(0xa2), set-request(0xa3), get-bulk(0xa5),
+    //inform(0xa6), snmpV2-trap(0xa7), report(0xa8). The SNMPv1 Trap-PDU (0xa4) has a DIFFERENT body
+    //(enterprise/agent-addr/generic/specific/timestamp/varbinds), so it — and any unknown tag — is kept
+    //verbatim (pduRaw) rather than misparsed, preserving a byte-perfect round-trip.
+    static #RFC3416_PDU_TAGS = new Set([0xa0, 0xa1, 0xa2, 0xa3, 0xa5, 0xa6, 0xa7, 0xa8]);
+    get SCHEMA() {
+        return (SNMP.#schemaCache ??= SNMP.#buildSchema());
+    }
+    // ===== Minimal BER/DER codec (definite length only) =====
+    /** Read one TLV at `pos`; defensive against truncation (always advances, clamps to buffer). */
+    static #readTLV(buf, pos) {
+        if (pos >= buf.length)
+            return { tag: 0, contentStart: pos, contentLen: 0, next: pos + 1 };
+        const tag = buf[pos];
+        let p = pos + 1;
+        let len = p < buf.length ? buf[p] : 0;
+        p += 1;
+        if (len & 0x80) {
+            const lengthBytes = len & 0x7f;
+            len = 0;
+            for (let i = 0; i < lengthBytes; i++) {
+                len = len * 256 + (p < buf.length ? buf[p] : 0);
+                p += 1;
+            }
+        }
+        const contentStart = p;
+        //Clamp the content to what is actually present so a lying length cannot read out of bounds.
+        const contentLen = Math.min(len, Math.max(0, buf.length - contentStart));
+        return { tag: tag, contentStart: contentStart, contentLen: contentLen, next: contentStart + contentLen };
+    }
+    /** Decode a BER INTEGER content (big-endian two's-complement, signed). */
+    static #berInt(buf) {
+        if (buf.length === 0)
+            return 0;
+        let value = 0;
+        for (const byte of buf)
+            value = value * 256 + byte;
+        if (buf[0] & 0x80)
+            value -= Math.pow(2, 8 * buf.length);
+        return value;
+    }
+    /** Encode a signed integer as minimal BER INTEGER content bytes. */
+    static #intToBer(value) {
+        const bytes = [];
+        let v = Math.trunc(value);
+        if (v >= 0) {
+            do {
+                bytes.unshift(v & 0xff);
+                v = Math.floor(v / 256);
+            } while (v > 0);
+            if (bytes[0] & 0x80)
+                bytes.unshift(0);
+        }
+        else {
+            do {
+                bytes.unshift(v & 0xff);
+                v = Math.floor(v / 256);
+            } while (v < -1);
+            if (!(bytes[0] & 0x80))
+                bytes.unshift(0xff);
+        }
+        return Buffer.from(bytes);
+    }
+    /** Decode a BER OBJECT IDENTIFIER content into a dotted string. */
+    static #oidToStr(buf) {
+        const subs = [];
+        let value = 0;
+        for (let i = 0; i < buf.length; i++) {
+            value = value * 128 + (buf[i] & 0x7f);
+            if (!(buf[i] & 0x80)) {
+                subs.push(value);
+                value = 0;
+            }
+        }
+        if (subs.length === 0)
+            return '';
+        const first = subs[0];
+        const arc0 = first < 80 ? Math.floor(first / 40) : 2;
+        const arc1 = first - arc0 * 40;
+        return [arc0, arc1, ...subs.slice(1)].join('.');
+    }
+    /** Encode a dotted OID string into BER OBJECT IDENTIFIER content bytes (base-128 sub-identifiers). */
+    static #strToOid(oid) {
+        const arcs = oid.split('.').map((arc) => Number(arc) || 0);
+        const subs = [];
+        if (arcs.length >= 2)
+            subs.push(arcs[0] * 40 + arcs[1]);
+        else if (arcs.length === 1)
+            subs.push(arcs[0] * 40);
+        for (let i = 2; i < arcs.length; i++)
+            subs.push(arcs[i]);
+        const bytes = [];
+        for (const sub of subs) {
+            const group = [];
+            let v = sub;
+            do {
+                group.unshift(v & 0x7f);
+                v = Math.floor(v / 128);
+            } while (v > 0);
+            for (let i = 0; i < group.length - 1; i++)
+                group[i] |= 0x80;
+            bytes.push(...group);
+        }
+        return Buffer.from(bytes);
+    }
+    /** Encode a definite length in minimal form (short form < 128, else long form). */
+    static #encodeLength(length) {
+        if (length < 0x80)
+            return Buffer.from([length]);
+        const bytes = [];
+        let v = length;
+        while (v > 0) {
+            bytes.unshift(v & 0xff);
+            v = Math.floor(v / 256);
+        }
+        return Buffer.from([0x80 | bytes.length, ...bytes]);
+    }
+    /** Build a complete TLV: tag + minimal length + content. */
+    static #tlv(tag, content) {
+        return Buffer.concat([Buffer.from([tag]), this.#encodeLength(content.length), content]);
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'SNMP ${community} req=${requestId}',
+            properties: {
+                //SNMP is one nested BER blob, so the whole message is parsed here (and emitted in the
+                //matching encode) rather than field-by-field at fixed offsets. The remaining properties
+                //below carry only schema/label/validation metadata; they have no closures of their own.
+                version: {
+                    type: 'integer',
+                    label: 'Version',
+                    minimum: 0,
+                    maximum: 3,
+                    decode: function () {
+                        const available = this.packet.length - this.startPos;
+                        if (available <= 0)
+                            return;
+                        //Peek the outer SEQUENCE header to learn the whole-message length (the length
+                        //field is read UNCLAMPED here — the peek is only long enough for the header, so
+                        //#readTLV's content clamp would wrongly cap the total), then read the whole
+                        //message (non-dry-run) so headerLength/endPos cover exactly the BER message.
+                        const peek = this.readBytes(0, available < 8 ? available : 8, true);
+                        let hp = 1;
+                        let declaredLength = hp < peek.length ? peek[hp] : 0;
+                        hp += 1;
+                        if (declaredLength & 0x80) {
+                            const lengthBytes = declaredLength & 0x7f;
+                            declaredLength = 0;
+                            for (let i = 0; i < lengthBytes; i++) {
+                                declaredLength = declaredLength * 256 + (hp < peek.length ? peek[hp] : 0);
+                                hp += 1;
+                            }
+                        }
+                        const total = Math.min(hp + declaredLength, available);
+                        const buf = this.readBytes(0, total > 0 ? total : 0);
+                        const message = SNMP.#readTLV(buf, 0);
+                        let p = message.contentStart;
+                        const versionTLV = SNMP.#readTLV(buf, p);
+                        this.instance.version.setValue(SNMP.#berInt(buf.subarray(versionTLV.contentStart, versionTLV.next)));
+                        p = versionTLV.next;
+                        const communityTLV = SNMP.#readTLV(buf, p);
+                        this.instance.community.setValue(buf.subarray(communityTLV.contentStart, communityTLV.next).toString('latin1'));
+                        p = communityTLV.next;
+                        const pduTLV = SNMP.#readTLV(buf, p);
+                        this.instance.pduType.setValue(pduTLV.tag);
+                        if (!SNMP.#RFC3416_PDU_TAGS.has(pduTLV.tag)) {
+                            //Non-RFC-3416 PDU (SNMPv1 Trap 0xa4, or an unknown tag): keep the body bytes
+                            //verbatim so it round-trips exactly. Structured fields are left unset;
+                            //semantic decoding of the v1 trap body is a later enrichment.
+                            this.instance.pduRaw.setValue(buf.subarray(pduTLV.contentStart, pduTLV.next).toString('hex'));
+                            return;
+                        }
+                        let pp = pduTLV.contentStart;
+                        const requestIdTLV = SNMP.#readTLV(buf, pp);
+                        this.instance.requestId.setValue(SNMP.#berInt(buf.subarray(requestIdTLV.contentStart, requestIdTLV.next)));
+                        pp = requestIdTLV.next;
+                        const errorStatusTLV = SNMP.#readTLV(buf, pp);
+                        this.instance.errorStatus.setValue(SNMP.#berInt(buf.subarray(errorStatusTLV.contentStart, errorStatusTLV.next)));
+                        pp = errorStatusTLV.next;
+                        const errorIndexTLV = SNMP.#readTLV(buf, pp);
+                        this.instance.errorIndex.setValue(SNMP.#berInt(buf.subarray(errorIndexTLV.contentStart, errorIndexTLV.next)));
+                        pp = errorIndexTLV.next;
+                        const bindingsTLV = SNMP.#readTLV(buf, pp);
+                        const varbinds = [];
+                        let vp = bindingsTLV.contentStart;
+                        while (vp < bindingsTLV.next && vp < buf.length) {
+                            const bindTLV = SNMP.#readTLV(buf, vp);
+                            let ip = bindTLV.contentStart;
+                            const oidTLV = SNMP.#readTLV(buf, ip);
+                            const oid = SNMP.#oidToStr(buf.subarray(oidTLV.contentStart, oidTLV.next));
+                            ip = oidTLV.next;
+                            const valueTLV = SNMP.#readTLV(buf, ip);
+                            varbinds.push({
+                                oid: oid,
+                                valueType: valueTLV.tag,
+                                value: buf.subarray(valueTLV.contentStart, valueTLV.next).toString('hex')
+                            });
+                            vp = bindTLV.next;
+                        }
+                        this.instance.variableBindings.setValue(varbinds);
+                    },
+                    encode: function () {
+                        const version = this.instance.version.getValue(0);
+                        const community = this.instance.community.getValue('');
+                        const pduType = this.instance.pduType.getValue(0xa0);
+                        const requestId = this.instance.requestId.getValue(0);
+                        const errorStatus = this.instance.errorStatus.getValue(0);
+                        const errorIndex = this.instance.errorIndex.getValue(0);
+                        const pduRaw = this.instance.pduRaw.getValue('');
+                        let pduContent;
+                        if (pduRaw) {
+                            //A non-RFC-3416 PDU kept verbatim (e.g. SNMPv1 trap): re-emit its body as-is.
+                            pduContent = Buffer.from(pduRaw, 'hex');
+                        }
+                        else {
+                            const varbinds = this.instance.variableBindings.getValue([]);
+                            const bindBuffers = (varbinds ? varbinds : []).map((varbind) => {
+                                const oidBuffer = SNMP.#tlv(0x06, SNMP.#strToOid(varbind.oid ? varbind.oid : ''));
+                                const valueBuffer = SNMP.#tlv(varbind.valueType ? varbind.valueType : 0x05, Buffer.from(varbind.value ? varbind.value : '', 'hex'));
+                                return SNMP.#tlv(0x30, Buffer.concat([oidBuffer, valueBuffer]));
+                            });
+                            pduContent = Buffer.concat([
+                                SNMP.#tlv(0x02, SNMP.#intToBer(requestId)),
+                                SNMP.#tlv(0x02, SNMP.#intToBer(errorStatus)),
+                                SNMP.#tlv(0x02, SNMP.#intToBer(errorIndex)),
+                                SNMP.#tlv(0x30, Buffer.concat(bindBuffers))
+                            ]);
+                        }
+                        const message = SNMP.#tlv(0x30, Buffer.concat([
+                            SNMP.#tlv(0x02, SNMP.#intToBer(version)),
+                            SNMP.#tlv(0x04, Buffer.from(community, 'latin1')),
+                            SNMP.#tlv(pduType, pduContent)
+                        ]));
+                        this.writeBytes(0, message);
+                    }
+                },
+                community: { type: 'string', label: 'Community' },
+                //The PDU context tag: 0xa0 get-request, 0xa1 get-next-request, 0xa2 get-response,
+                //0xa3 set-request, 0xa5 get-bulk-request, 0xa6 inform-request, 0xa7 snmpV2-trap, 0xa8 report.
+                pduType: { type: 'integer', label: 'PDU Type', minimum: 0, maximum: 255 },
+                //Verbatim PDU body for non-RFC-3416 PDUs (SNMPv1 Trap 0xa4 / unknown tags). Hidden and
+                //empty for the common request/response PDUs, which use the structured fields below.
+                pduRaw: { type: 'string', label: 'PDU Body', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX, hidden: true },
+                requestId: { type: 'integer', label: 'Request ID' },
+                errorStatus: { type: 'integer', label: 'Error Status', minimum: 0 },
+                errorIndex: { type: 'integer', label: 'Error Index', minimum: 0 },
+                variableBindings: {
+                    type: 'array',
+                    label: 'Variable Bindings',
+                    items: {
+                        type: 'object',
+                        label: 'Variable Binding',
+                        properties: {
+                            oid: { type: 'string', label: 'Object Identifier' },
+                            valueType: { type: 'integer', label: 'Value Type', minimum: 0, maximum: 255 },
+                            value: { type: 'string', label: 'Value', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX }
+                        }
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        return !!this.prevCodecModule && this.prevCodecModule.id === 'udp';
+    }
+}
+exports.SNMP = SNMP;

package/dist/headers/SOCKS4.d.ts

@@ -0,0 +1,42 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * SOCKS4 — the SOCKS Protocol Version 4 (and the SOCKS4a extension), carried over TCP well-known
+ * port 1080. Only two message shapes travel on the wire, discriminated by their leading octet:
+ *
+ *   1. Client request : version(1,=4) · command(1: 1 CONNECT / 2 BIND) · dstPort(2, BE) ·
+ *                        dstIp(4, IPv4) · userId(null-terminated ASCII) [· domain(null-terminated)]
+ *   2. Server reply   : null(1,=0) · status(1: 0x5A granted, 0x5B/0x5C/0x5D rejected) ·
+ *                        dstPort(2, BE) · dstIp(4, IPv4)   — always exactly 8 octets
+ *
+ * The two shapes share their tail exactly — dstPort at offset 2 and dstIp at offset 4 — so those
+ * fields are common to both; only the leading octet (version 4 vs null 0), the second octet
+ * (command vs status), and the request's trailing user-id are shape-specific. A `messageType`
+ * display field ('request' | 'reply') is the discriminator, decoded from the leading octet
+ * (4 → request, 0 → reply) and driving every field below.
+ *
+ * SOCKS4a: when the request's dstIp is 0.0.0.x (first three octets zero, last non-zero) the client
+ * could not resolve the host and appends a second null-terminated string — the destination domain —
+ * after the user-id. The codec structures that trailing string as `domain` whenever bytes remain
+ * after the user-id's terminator, so both plain SOCKS4 and SOCKS4a requests round-trip byte-for-byte.
+ * (A request whose user-id lacks its RFC-mandated null terminator is malformed: it decodes
+ * best-effort but re-emits with the terminator, so the byte-perfect guarantee is for conformant
+ * SOCKS4 only.)
+ *
+ * Matching rationale (NO heuristicFallback): SOCKS4 is claimed ONLY on the tcp:1080 bucket. Its only
+ * content signature is a single leading octet of 0x04 (request) or 0x00 (reply) — a signature that
+ * matches enormous amounts of arbitrary binary TCP data; recognition therefore depends entirely on
+ * the well-known port. Joining the global content-heuristic chain would mislabel unrelated binary
+ * traffic on any port, so SOCKS4 is confined to tcp:1080 and alt-port SOCKS4 falls losslessly to raw.
+ */
+export declare class SOCKS4 extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}