@netkitty/codec 1.0.0

package/dist/headers/XMPP.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XMPP = 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");
+/**
+ * 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.
+ */
+class XMPP extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'xmpp';
+        this.name = 'Extensible Messaging and Presence Protocol';
+        this.nickname = 'XMPP';
+        //Client-to-server (5222) and server-to-server (5269) TCP ports. Port-bucket dispatch only, NO
+        //heuristicFallback: an XML fragment beginning with '<' is far too weak a signature to claim arbitrary
+        //TCP traffic off these ports, so XMPP is recognized solely on 5222/5269 (matching the SIP precedent
+        //for a generic text protocol).
+        this.matchKeys = ['tcpport:5222', 'tcpport:5269'];
+        //A leaf header — the XML stanza tree and the stream session it belongs to are a higher-layer concern.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (XMPP.#schemaCache ??= XMPP.#buildSchema());
+    }
+    /**
+     * Bytes of this header: XMPP rides on TCP, which has no per-message length. Bound the payload by the
+     * enclosing IP datagram (IP total length) so a short XML fragment does not absorb Ethernet minimum-frame
+     * padding; fall back to the rest of the captured segment when no IP layer is present. Segment reassembly
+     * is out of scope (see class doc).
+     */
+    #payloadLength() {
+        let available = this.packet.length - this.startPos;
+        //Walk back to the enclosing IP layer (prevCodecModule is the TCP header) to cap at the IP payload.
+        for (let i = this.prevCodecModules.length - 1; i >= 0; i--) {
+            const module = this.prevCodecModules[i];
+            if (module.id === 'ipv4') {
+                const ipEnd = module.startPos + module.instance.length.getValue(0);
+                const bounded = ipEnd - this.startPos;
+                if (bounded >= 0 && bounded < available)
+                    available = bounded;
+                break;
+            }
+            if (module.id === 'ipv6') {
+                const ipEnd = module.startPos + module.length + module.instance.plen.getValue(0);
+                const bounded = ipEnd - this.startPos;
+                if (bounded >= 0 && bounded < available)
+                    available = bounded;
+                break;
+            }
+        }
+        return available < 0 ? 0 : available;
+    }
+    /**
+     * Parse the fragment head into the display-only metadata fields. Populated on decode only — these
+     * fields have no encode, so they never affect the re-emitted bytes and never mutate `message`. Never
+     * throws: a fragment with no recognizable start tag yields an empty rootElement.
+     */
+    #parseMetadata(text) {
+        //Skip an optional leading XML declaration (`<?xml … ?>`), then find the first element start tag.
+        const declaration = text.match(/^\s*<\?xml\b[^>]*\?>/);
+        const rest = declaration ? text.slice(declaration[0].length) : text;
+        //First start-tag name: `<` then the tag name up to whitespace, `>` or `/` (closing tags start
+        //with `/`, excluded from the first char class, so `</stream:stream>` is not matched as a name).
+        const element = rest.match(/<([^\s>/!?][^\s>/]*)/);
+        const name = element ? element[1] : '';
+        this.instance.rootElement.setValue(name);
+        this.instance.isStreamHeader.setValue(name === 'stream:stream');
+        this.instance.hasXmlDeclaration.setValue(!!declaration);
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'XMPP ${rootElement}',
+            properties: {
+                //The whole raw payload is the single source of truth: decoded verbatim to hex and
+                //re-emitted untouched (byte-perfect for any XMPP fragment). The fragment head is parsed
+                //into the display-only metadata below, which carry no codec of their own.
+                message: {
+                    type: 'string',
+                    label: 'Message',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const available = this.#payloadLength();
+                        if (available <= 0) {
+                            this.instance.message.setValue('');
+                            this.#parseMetadata('');
+                            return;
+                        }
+                        const raw = this.readBytes(0, available);
+                        this.instance.message.setValue((0, BufferToHex_1.BufferToHex)(raw));
+                        this.#parseMetadata(raw.toString('latin1'));
+                    },
+                    encode: function () {
+                        //Re-emit the authoritative payload verbatim — never reconstruct from metadata.
+                        this.writeBytes(0, (0, HexToBuffer_1.HexToBuffer)(this.instance.message.getValue('')));
+                    }
+                },
+                //Display-only metadata parsed from the fragment head on decode (no encode — populated by the
+                //message field above, never read back). rootElement is the first element's tag name (e.g.
+                //'stream:stream', 'message', 'iq', 'presence'); isStreamHeader flags the stream preamble;
+                //hasXmlDeclaration flags a leading `<?xml … ?>`.
+                rootElement: { type: 'string', label: 'Root Element' },
+                isStreamHeader: { type: 'boolean', label: 'Is Stream Header' },
+                hasXmlDeclaration: { type: 'boolean', label: 'Has XML Declaration' }
+            }
+        };
+    }
+    match() {
+        //XMPP rides on TCP ports 5222/5269 as an XML text stream. Beyond the port bucket, require the
+        //first non-whitespace byte of the fragment to be '<' (an XML declaration or element start) so
+        //non-XML traffic on these ports — e.g. a TLS record after STARTTLS (leading 0x16) — falls through
+        //to raw rather than claiming an un-decodable text layer. Guard on the transport-payload length
+        //(not the whole frame remainder) so Ethernet padding is not mistaken for a fragment.
+        if (!this.prevCodecModule)
+            return false;
+        if (this.prevCodecModule.id !== 'tcp')
+            return false;
+        if (this.#payloadLength() <= 0)
+            return false;
+        const lead = this.readBytes(0, 16, true).toString('latin1');
+        return lead.replace(/^\s+/, '').startsWith('<');
+    }
+}
+exports.XMPP = XMPP;

package/dist/headers/Zabbix.d.ts

@@ -0,0 +1,35 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * Zabbix protocol (the Zabbix server / agent / sender header), TCP port 10051 (and 10050 for the
+ * passive agent). Every message begins with a fixed 13-byte header — a 4-byte Magic ("ZBXD",
+ * 0x5A425844), a 1-byte Flags octet (0x01 uncompressed, 0x02 compressed, 0x04 large-packet), a 4-byte
+ * Data Length and a 4-byte Reserved field — followed by `Data Length` bytes of body (a JSON request /
+ * response, or, when the compressed flag is set, zlib-deflated JSON with the uncompressed size carried
+ * in Reserved).
+ *
+ * ⚠️ Both length fields are LITTLE-ENDIAN (Zabbix serializes them low byte first). There is no
+ * little-endian helper in this codebase, so the uint32 fields are read and written byte-by-byte in
+ * their closures. For the classic (non large-packet) header Data Length / Reserved are 32-bit; the
+ * large-packet variant widens them to 64 bits, which is out of scope for this 13-byte header — the
+ * low 32 bits are decoded and a body beyond 4 GiB is not a concern for a single captured segment.
+ *
+ * The body is the JSON payload (or compressed blob); it is application-level, cross-message state, so
+ * this single-message codec keeps it verbatim as `body` hex (byte-perfect) and does not parse the JSON.
+ * Data Length is auto-computed from the body on encode when not supplied, else honored verbatim (a
+ * crafted message may lie); the body is bounded by Data Length and the captured bytes so a pipelined /
+ * trailing message is left to the codec's recursion / RawData. Reserved is honored verbatim. A
+ * well-formed message round-trips byte-for-byte.
+ */
+export declare class Zabbix 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/Zabbix.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Zabbix = 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");
+/**
+ * Zabbix protocol (the Zabbix server / agent / sender header), TCP port 10051 (and 10050 for the
+ * passive agent). Every message begins with a fixed 13-byte header — a 4-byte Magic ("ZBXD",
+ * 0x5A425844), a 1-byte Flags octet (0x01 uncompressed, 0x02 compressed, 0x04 large-packet), a 4-byte
+ * Data Length and a 4-byte Reserved field — followed by `Data Length` bytes of body (a JSON request /
+ * response, or, when the compressed flag is set, zlib-deflated JSON with the uncompressed size carried
+ * in Reserved).
+ *
+ * ⚠️ Both length fields are LITTLE-ENDIAN (Zabbix serializes them low byte first). There is no
+ * little-endian helper in this codebase, so the uint32 fields are read and written byte-by-byte in
+ * their closures. For the classic (non large-packet) header Data Length / Reserved are 32-bit; the
+ * large-packet variant widens them to 64 bits, which is out of scope for this 13-byte header — the
+ * low 32 bits are decoded and a body beyond 4 GiB is not a concern for a single captured segment.
+ *
+ * The body is the JSON payload (or compressed blob); it is application-level, cross-message state, so
+ * this single-message codec keeps it verbatim as `body` hex (byte-perfect) and does not parse the JSON.
+ * Data Length is auto-computed from the body on encode when not supplied, else honored verbatim (a
+ * crafted message may lie); the body is bounded by Data Length and the captured bytes so a pipelined /
+ * trailing message is left to the codec's recursion / RawData. Reserved is honored verbatim. A
+ * well-formed message round-trips byte-for-byte.
+ */
+class Zabbix extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'zabbix';
+        this.name = 'Zabbix Protocol';
+        this.nickname = 'Zabbix';
+        //Well-known Zabbix server port 10051. heuristicFallback because "ZBXD" is a reliable 4-byte content
+        //signature — the Zabbix server/proxy/agent/sender speak the same framing on other ports (10050 for
+        //the passive agent, arbitrary sender ports), so it must also be recognized off 10051 via match().
+        this.matchKeys = ['tcpport:10051'];
+        this.heuristicFallback = true;
+        //A leaf header — the JSON/compressed body is application-level, cross-message state.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (Zabbix.#schemaCache ??= Zabbix.#buildSchema());
+    }
+    /** A little-endian unsigned 32-bit field of 4 octets at `offset`. */
+    static #fieldUInt32LE(name, offset, label) {
+        return {
+            type: 'integer',
+            label: label,
+            minimum: 0,
+            maximum: 4294967295,
+            decode: function () {
+                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 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]));
+            }
+        };
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'Zabbix flags=${flags} len=${dataLength}',
+            properties: {
+                //The 4-byte protocol Magic — always "ZBXD" (0x5A425844) on the wire; kept verbatim so any
+                //non-standard magic still round-trips.
+                magic: this.fieldHex('magic', 0, 4, 'Magic'),
+                //Flags bitfield: 0x01 ZBX_TCP_PROTOCOL (uncompressed), 0x02 ZBX_TCP_COMPRESS, 0x04
+                //ZBX_TCP_LARGE. Kept as a plain uint8 (byte-perfect and editable); the bit split is UI
+                //enrichment for later.
+                flags: this.fieldUInt('flags', 4, 1, 'Flags'),
+                dataLength: {
+                    type: 'integer',
+                    label: 'Data Length',
+                    minimum: 0,
+                    maximum: 4294967295,
+                    decode: function () {
+                        const b = this.readBytes(5, 4);
+                        this.instance.dataLength.setValue((b[0] | (b[1] << 8) | (b[2] << 16) | (b[3] << 24)) >>> 0);
+                    },
+                    encode: function () {
+                        //Data Length counts only the body that follows the 13-byte header (LITTLE-ENDIAN).
+                        //Honored when supplied (a crafted message may lie); else derived from the body.
+                        const provided = this.instance.dataLength.getValue();
+                        let value = (provided !== undefined && provided !== null)
+                            ? provided
+                            : (0, HexToBuffer_1.HexToBuffer)(this.instance.body.getValue('')).length;
+                        if (value > 4294967295) {
+                            this.recordError(this.instance.dataLength.getPath(), 'Maximum value is 4294967295');
+                            value = 4294967295;
+                        }
+                        if (value < 0) {
+                            this.recordError(this.instance.dataLength.getPath(), 'Minimum value is 0');
+                            value = 0;
+                        }
+                        this.instance.dataLength.setValue(value);
+                        this.writeBytes(5, Buffer.from([value & 0xff, (value >> 8) & 0xff, (value >> 16) & 0xff, (value >>> 24) & 0xff]));
+                    }
+                },
+                //Reserved (LITTLE-ENDIAN): zero for an uncompressed message, the uncompressed body size
+                //when the compressed flag (0x02) is set. Honored verbatim — a byte-perfect passthrough.
+                reserved: this.#fieldUInt32LE('reserved', 9, 'Reserved'),
+                //The body (JSON request/response, or a zlib-deflated blob when compressed), kept verbatim.
+                //Bounded by Data Length (body ends at offset 13 + Data Length) 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.packet.length - this.startPos;
+                        const length = this.instance.dataLength.getValue(0);
+                        let end = 13 + length;
+                        if (end > remaining)
+                            end = remaining;
+                        this.instance.body.setValue(end > 13 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(13, end - 13)) : '');
+                    },
+                    encode: function () {
+                        const body = this.instance.body.getValue('');
+                        if (body)
+                            this.writeBytes(13, (0, HexToBuffer_1.HexToBuffer)(body));
+                    }
+                }
+            }
+        };
+    }
+    match() {
+        //Zabbix rides on TCP. Require the full 13-byte header and the "ZBXD" Magic (0x5A425844) so
+        //non-Zabbix traffic falls through to raw. The magic is a strong 32-bit content signature — safe
+        //to match on any port; the full-header guard keeps a crafted short frame from being claimed and
+        //breaking the byte-perfect body bound.
+        if (!this.prevCodecModule || this.prevCodecModule.id !== 'tcp')
+            return false;
+        if (this.packet.length - this.startPos < 13)
+            return false;
+        return (0, BufferToHex_1.BufferToHex)(this.readBytes(0, 4, true)) === '5a425844';
+    }
+}
+exports.Zabbix = Zabbix;

package/dist/headers/cms/AcsiPdu.d.ts

@@ -0,0 +1,45 @@
+import { AsnType } from './PerDecoder';
+/**
+ * GetAllDataDefinition-RequestPDU (SC 155, §8.3.5.3). A 3-field SEQUENCE (not extensible): a `reference`
+ * CHOICE between a bare logical-device name and a logical-node reference, an OPTIONAL functional
+ * constraint, and an OPTIONAL "reference after" cursor for paging. Verified byte-for-byte against a real
+ * frame whose service data `22 00` + "SW111103SWI/LLN0" decodes as preamble(00) + choice-index(1,
+ * lnReference) + length(16) + the octet-aligned reference.
+ */
+export declare const GET_ALL_DATA_DEFINITION_REQUEST: AsnType;
+/**
+ * AssociateNegotiate-RequestPDU / -ResponsePDU (SC 154, §8.15.1.3). The session-opening capability
+ * exchange: negotiated APDU size, declared max ASDU size, and protocol version (0x201 = 2.1); the
+ * response adds the model version string. All fields mandatory, not extensible. Verified against a real
+ * frame whose 9-byte service data `fd e8 03 02 00 00 02 02 01` decodes to
+ * {apduSize: 65000, asduSize: 131072, protocolVersion: 513}.
+ */
+export declare const ASSOCIATE_NEGOTIATE_REQUEST: AsnType;
+export declare const ASSOCIATE_NEGOTIATE_RESPONSE: AsnType;
+/**
+ * GetAllDataValues-RequestPDU (SC 83, §8.3.4.3) is structurally identical to GetAllDataDefinition's request
+ * (a reference CHOICE plus optional functional-constraint and paging cursor) per the standard, so it reuses
+ * the same PER descriptor. Its response, by contrast, carries `Data` values encoded as GB/T 33602 TLV, not
+ * PER, and is decoded separately (not via this PER descriptor table).
+ */
+export declare const GET_ALL_DATA_VALUES_REQUEST: AsnType;
+/**
+ * Associate-RequestPDU (SC 1, §8.2.1.4). Both fields OPTIONAL: an optional server access-point reference
+ * and an optional authentication parameter (signature certificate + signed UTC time + signed value). A real
+ * frame carries both absent (service data `00` = the 2-bit preamble, both cleared). VisibleString129 =
+ * VisibleString(SIZE(0..129)); UtcTime = OCTET STRING(SIZE(8)).
+ */
+export declare const ASSOCIATE_REQUEST: AsnType;
+export interface ServicePdu {
+    request?: AsnType;
+    response?: AsnType;
+}
+/**
+ * Service Code → PDU descriptors. Only services whose ASN.1 has been transcribed and verified against a
+ * real frame appear here; an absent service (or an untranscribed direction) leaves the service data as
+ * verbatim hex. GetAllDataDefinition's response references a not-yet-transcribed `DataDefinition` type, so
+ * only the request is structured for now.
+ */
+export declare const SERVICE_PDU: Record<number, ServicePdu>;
+/** Service Code → name (DL/T 2811-2024 §6.1.2 Table 1), for the display label. */
+export declare const SERVICE_NAMES: Record<number, string>;

package/dist/headers/cms/AcsiPdu.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_NAMES = exports.SERVICE_PDU = exports.ASSOCIATE_REQUEST = exports.GET_ALL_DATA_VALUES_REQUEST = exports.ASSOCIATE_NEGOTIATE_RESPONSE = exports.ASSOCIATE_NEGOTIATE_REQUEST = exports.GET_ALL_DATA_DEFINITION_REQUEST = void 0;
+/**
+ * AcsiPdu — ASN.1 type descriptors for CMS (DL/T 2811-2024) ACSI service PDUs, transcribed from the
+ * standard for the {@link PerDecoder} (ALIGNED BASIC-PER, §6.10). These live on the imperative side of the
+ * codec's schema split; each service is one entry in {@link SERVICE_PDU}, keyed by its Service Code, so
+ * adding a service is a local addition and never a core change. PER ignores the IMPLICIT `[n]` tags in the
+ * printed notation (tags are a BER concern only), so they are omitted here — only the structure, order,
+ * optionality and SIZE/value constraints matter.
+ */
+//Common ACSI reference types (DL/T 2811-2024 §7.3): plain VisibleStrings with a SIZE constraint.
+const OBJECT_NAME = { k: 'vstr', min: 0, max: 64 }; //ObjectName ::= VisibleString(SIZE(0..64))   §7.3.1
+const OBJECT_REFERENCE = { k: 'vstr', min: 0, max: 129 }; //ObjectReference ::= VisibleString(SIZE(0..129)) §7.3.2
+//FunctionalConstraint ::= VisibleString(SIZE(2)) §7.4.1.2 — a fixed 2-char code (ST, MX, CF, …), not an enum.
+const FUNCTIONAL_CONSTRAINT = { k: 'vstr', min: 2, max: 2 };
+/**
+ * GetAllDataDefinition-RequestPDU (SC 155, §8.3.5.3). A 3-field SEQUENCE (not extensible): a `reference`
+ * CHOICE between a bare logical-device name and a logical-node reference, an OPTIONAL functional
+ * constraint, and an OPTIONAL "reference after" cursor for paging. Verified byte-for-byte against a real
+ * frame whose service data `22 00` + "SW111103SWI/LLN0" decodes as preamble(00) + choice-index(1,
+ * lnReference) + length(16) + the octet-aligned reference.
+ */
+exports.GET_ALL_DATA_DEFINITION_REQUEST = {
+    k: 'seq',
+    fields: [
+        { name: 'reference', type: { k: 'choice', alts: [
+                    { name: 'ldName', type: OBJECT_NAME },
+                    { name: 'lnReference', type: OBJECT_REFERENCE }
+                ] } },
+        { name: 'fc', type: FUNCTIONAL_CONSTRAINT, optional: true },
+        { name: 'referenceAfter', type: OBJECT_REFERENCE, optional: true }
+    ]
+};
+//Common ACSI integer/string base types (DL/T 2811-2024 §7.1). INT16U is fully constrained (fixed width
+//in PER); INT32U is semi-constrained INTEGER(0..MAX) (length-prefixed octets); a bare VisibleString has no
+//SIZE bound (length determinant + content).
+const INT16U = { k: 'int', lb: 0, ub: 65535 };
+const INT32U = { k: 'int', lb: 0 };
+const VISIBLE_STRING = { k: 'vstr' };
+/**
+ * AssociateNegotiate-RequestPDU / -ResponsePDU (SC 154, §8.15.1.3). The session-opening capability
+ * exchange: negotiated APDU size, declared max ASDU size, and protocol version (0x201 = 2.1); the
+ * response adds the model version string. All fields mandatory, not extensible. Verified against a real
+ * frame whose 9-byte service data `fd e8 03 02 00 00 02 02 01` decodes to
+ * {apduSize: 65000, asduSize: 131072, protocolVersion: 513}.
+ */
+exports.ASSOCIATE_NEGOTIATE_REQUEST = {
+    k: 'seq',
+    fields: [
+        { name: 'apduSize', type: INT16U },
+        { name: 'asduSize', type: INT32U },
+        { name: 'protocolVersion', type: INT32U }
+    ]
+};
+exports.ASSOCIATE_NEGOTIATE_RESPONSE = {
+    k: 'seq',
+    fields: [
+        { name: 'apduSize', type: INT16U },
+        { name: 'asduSize', type: INT32U },
+        { name: 'protocolVersion', type: INT32U },
+        { name: 'modelVersion', type: VISIBLE_STRING }
+    ]
+};
+/**
+ * GetAllDataValues-RequestPDU (SC 83, §8.3.4.3) is structurally identical to GetAllDataDefinition's request
+ * (a reference CHOICE plus optional functional-constraint and paging cursor) per the standard, so it reuses
+ * the same PER descriptor. Its response, by contrast, carries `Data` values encoded as GB/T 33602 TLV, not
+ * PER, and is decoded separately (not via this PER descriptor table).
+ */
+exports.GET_ALL_DATA_VALUES_REQUEST = exports.GET_ALL_DATA_DEFINITION_REQUEST;
+/**
+ * Associate-RequestPDU (SC 1, §8.2.1.4). Both fields OPTIONAL: an optional server access-point reference
+ * and an optional authentication parameter (signature certificate + signed UTC time + signed value). A real
+ * frame carries both absent (service data `00` = the 2-bit preamble, both cleared). VisibleString129 =
+ * VisibleString(SIZE(0..129)); UtcTime = OCTET STRING(SIZE(8)).
+ */
+exports.ASSOCIATE_REQUEST = {
+    k: 'seq',
+    fields: [
+        { name: 'serverAccessPointReference', type: { k: 'vstr', min: 0, max: 129 }, optional: true },
+        { name: 'authenticationParameter', type: { k: 'seq', fields: [
+                    { name: 'signatureCertificate', type: { k: 'octstr' } },
+                    { name: 'signedTime', type: { k: 'octstr', size: 8 } },
+                    { name: 'signedValue', type: { k: 'octstr' } }
+                ] }, optional: true }
+    ]
+};
+/**
+ * Service Code → PDU descriptors. Only services whose ASN.1 has been transcribed and verified against a
+ * real frame appear here; an absent service (or an untranscribed direction) leaves the service data as
+ * verbatim hex. GetAllDataDefinition's response references a not-yet-transcribed `DataDefinition` type, so
+ * only the request is structured for now.
+ */
+exports.SERVICE_PDU = {
+    1: { request: exports.ASSOCIATE_REQUEST },
+    83: { request: exports.GET_ALL_DATA_VALUES_REQUEST },
+    154: { request: exports.ASSOCIATE_NEGOTIATE_REQUEST, response: exports.ASSOCIATE_NEGOTIATE_RESPONSE },
+    155: { request: exports.GET_ALL_DATA_DEFINITION_REQUEST }
+};
+/** Service Code → name (DL/T 2811-2024 §6.1.2 Table 1), for the display label. */
+exports.SERVICE_NAMES = {
+    1: 'Associate',
+    2: 'Abort',
+    3: 'Release',
+    48: 'GetDataValues',
+    83: 'GetAllDataValues',
+    153: 'Test',
+    154: 'AssociateNegotiate',
+    155: 'GetAllDataDefinition',
+    156: 'GetAllCBValues'
+};

package/dist/headers/cms/PerDecoder.d.ts

@@ -0,0 +1,68 @@
+/**
+ * AsnType — a compact discriminated-union descriptor for the ASN.1 constructs CMS (DL/T 2811-2024) ACSI
+ * uses. This lives on the imperative side of the codec's schema split (it is procedural, not serializable
+ * JSON Schema) and is interpreted by {@link PerDecoder} against ALIGNED BASIC-PER bytes. Descriptors are
+ * transcribed per service from the spec's §7/§8 and kept in a name→type table so recursive types
+ * (`Data`, object references) resolve through `{k: 'ref'}`.
+ */
+export type AsnType = {
+    k: 'bool';
+} | {
+    k: 'int';
+    lb?: number;
+    ub?: number;
+} | {
+    k: 'enum';
+    values: string[];
+    ext?: boolean;
+} | {
+    k: 'bitstr';
+    size?: number;
+} | {
+    k: 'octstr';
+    size?: number;
+} | {
+    k: 'vstr';
+    min?: number;
+    max?: number;
+} | {
+    k: 'seq';
+    ext?: boolean;
+    fields: AsnField[];
+} | {
+    k: 'seqof';
+    element: AsnType;
+} | {
+    k: 'choice';
+    ext?: boolean;
+    alts: {
+        name: string;
+        type: AsnType;
+    }[];
+} | {
+    k: 'ref';
+    name: string;
+};
+export interface AsnField {
+    name: string;
+    type: AsnType;
+    optional?: boolean;
+    default?: unknown;
+}
+export type AsnTypeTable = Record<string, AsnType>;
+/**
+ * PerDecoder — a never-throwing ALIGNED BASIC-PER interpreter. It walks an {@link AsnType} descriptor,
+ * pulling from a {@link PerReader}, and returns a plain JS value tree for DISPLAY only (CMS keeps the raw
+ * service-data bytes as the authoritative encode form, so this decoder never affects output bytes). When it
+ * meets something it cannot safely decode — a fragmented length, an unknown `ref`, or an extensible type
+ * whose additions are present — it sets {@link bailed} so the caller can fall back to showing raw hex.
+ */
+export declare class PerDecoder {
+    #private;
+    constructor(buf: Buffer, table?: AsnTypeTable);
+    /** True once the decoder hit a construct it could not safely decode; the result is then incomplete. */
+    get bailed(): boolean;
+    /** Bytes consumed so far (rounded down) — lets the caller show any trailing bytes as raw. */
+    get bytePos(): number;
+    decode(type: AsnType): unknown;
+}