@cosyte/mllp 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @cosyte/mllp
 
-> Send and receive HL7 v2 over a production-grade MLLP connection in a few lines — with framing, ACK correlation, auto-reconnect, and backpressure handled for you.
+> Send and receive HL7 v2 over a production-grade MLLP connection in a few lines, with framing, ACK correlation, auto-reconnect, and backpressure handled for you.
 
 [![npm version](https://img.shields.io/npm/v/@cosyte/mllp.svg)](https://www.npmjs.com/package/@cosyte/mllp)
 [![CI](https://img.shields.io/github/actions/workflow/status/cosyte/mllp/ci.yml?branch=main&label=CI)](https://github.com/cosyte/mllp/actions/workflows/ci.yml)
@@ -16,7 +16,7 @@ A developer-focused MLLP (Minimal Lower Layer Protocol) client and server for No
 ## Quickstart
 
 ```bash
-# pnpm (recommended) — also works with: npm install @cosyte/mllp  |  yarn add @cosyte/mllp
+# pnpm (recommended), also works with: npm install @cosyte/mllp  |  yarn add @cosyte/mllp
 pnpm add @cosyte/mllp
 ```
 
@@ -34,20 +34,20 @@ const client = await createStarterClient({ host: "localhost", port: 2575 });
 const ack = await client.send(Buffer.from("MSH|^~\\&|..."));
 ```
 
-The payload API is **Buffer-first** everywhere — HL7 v2 messages are raw bytes with caller-managed charset decoding.
+The payload API is **Buffer-first** everywhere. HL7 v2 messages are raw bytes with caller-managed charset decoding.
 
 ## MLLPS / TLS
 
-TLS is built on `node:tls` — no bundled TLS, no extra dependency. Certificate verification is **on
+TLS is built on `node:tls`: no bundled TLS, no extra dependency. Certificate verification is **on
 by default**; the server binds `127.0.0.1` by default and requires an explicit opt-in
 (`allowWildcardBind: true`) to bind all interfaces.
 
 ```ts
-// Server — plain TLS
+// Server: plain TLS
 const server = createServer({ tls: { cert: certPem, key: keyPem } });
 await server.listen(2575, "127.0.0.1");
 
-// Server — mutual TLS (ATNA ITI-19)
+// Server: mutual TLS (ATNA ITI-19)
 const server = createServer({
   tls: { cert: certPem, key: keyPem, ca: clientCaPem, clientAuth: "MUST" },
 });
@@ -57,7 +57,7 @@ const server = createServer({
 // Client
 const client = createClient({ host: "mllp.example.com", port: 2575, tls: { ca: caPem } });
 
-// Client — mutual TLS
+// Client: mutual TLS
 const client = createClient({
   host: "mllp.example.com",
   port: 2575,
@@ -68,9 +68,9 @@ const client = createClient({
 See the **MLLPS / TLS** doc for the `ClientAuth` table, the TLS 1.2 floor (IHE ATNA ITI-19), typed
 failure modes (`tls-verify` vs `tls-handshake`), and bind-safety details.
 
-## Fail-safe ACKs — the commit contract
+## Fail-safe ACKs: the commit contract
 
-A positive acknowledgement (`AA`) tells the sender *"you may forget this message — I have it."* So a
+A positive acknowledgement (`AA`) tells the sender *"you may forget this message. I have it."* So a
 receiver must never send one before the message is durably handled, or the message is silently lost.
 `@cosyte/mllp` makes that structural: pair `autoAck: 'AA'` with an `onMessage` handler and the server
 **awaits your handler (the durable-commit step) and only then ACKs**.
@@ -86,28 +86,33 @@ const server = createServer({
 
 Handler resolves ⇒ `AA`. Handler throws ⇒ `AE` (or `AR` via `MllpAckError`). **A positive ACK cannot
 precede a successful commit.** `autoAck: 'AA'` *without* a handler is documented as a
-transport-accept — "received and framed", not "processed".
+transport-accept: "received and framed", not "processed".
 
 ## What's in the box
 
 - **Client + server** with strict MLLP framing (`VT + payload + FS + CR`), ACK correlation, auto-reconnect with backoff, and backpressure.
-- **The commit contract** — a positive ACK can never precede a durable commit; an unparseable inbound can never yield a positive ACK.
-- **Explicit 6-state connection machine** (`CONNECTING | CONNECTED | DRAINING | RECONNECTING | DISCONNECTED | CLOSED`) with `stateChange` events — never socket flags.
+- **The commit contract**: a positive ACK can never precede a durable commit; an unparseable inbound can never yield a positive ACK.
+- **Explicit 6-state connection machine** (`CONNECTING | CONNECTED | DRAINING | RECONNECTING | DISCONNECTED | CLOSED`) with `stateChange` events, never socket flags.
 - **Lenient decoder, strict encoder** (Postel's Law) with **11 stable warning codes** carrying byte offsets. Tolerance is opt-in per flag; the server ships tolerant defaults.
-- **TLS (MLLPS)** — verification on by default, mutual TLS (`clientAuth: 'NONE' | 'WANT' | 'MUST'`), a TLS 1.2 floor per IHE ATNA ITI-19, and bind-safety guardrails (`127.0.0.1` default, wildcard binds require opt-in). `AbortSignal` on every awaitable and `Symbol.asyncDispose` on every closeable.
-- **PHI-safe diagnostics** — no error, warning, event payload, or stats object ever echoes a *run* of message content; a framing error carries at most the single byte at the structural violation.
-- **In-memory transport** (`@cosyte/mllp/testing`) — a deterministic, socket-free test double for fast, reliable tests.
-- **`@cosyte/hl7` as an optional peer** — the `@cosyte/mllp/ack-from-hl7` subpath builds ACKs from parsed messages when it's installed.
+- **TLS (MLLPS)**: verification on by default, mutual TLS (`clientAuth: 'NONE' | 'WANT' | 'MUST'`), a TLS 1.2 floor per IHE ATNA ITI-19, and bind-safety guardrails (`127.0.0.1` default, wildcard binds require opt-in). `AbortSignal` on every awaitable and `Symbol.asyncDispose` on every closeable.
+- **PHI-safe diagnostics**: no error, warning, event payload, or stats object ever echoes a *run* of message content; a framing error carries at most the single byte at the structural violation.
+- **In-memory transport** (`@cosyte/mllp/testing`): a deterministic, socket-free test double for fast, reliable tests.
+- **`@cosyte/hl7` as an optional peer**: the `@cosyte/mllp/ack-from-hl7` subpath builds ACKs from parsed messages when it's installed.
 - **Zero runtime dependencies.** Node stdlib only.
 
 ## What it deliberately does not do
 
-MLLP + ACK is **at-least-once at best** — your application owns idempotency and de-duplication
+MLLP + ACK is **at-least-once at best**. Your application owns idempotency and de-duplication
 (`MSH-10` + `MSH-7`). This package does not parse HL7 (use `@cosyte/hl7`), does not queue or replay
 unacked messages, does not decide clinical acceptance, does not speak MLLP **Release 2**, and ships
-no PKI. The full list is in the **Known limitations & non-goals** doc — read it before you depend on
+no PKI. The full list is in the **Known limitations & non-goals** doc. Read it before you depend on
 this.
 
+## Trademarks
+
+Epic, Cerner, Mirth Connect, NextGen, and Google Cloud Healthcare are trademarks of their respective owners. cosyte is not affiliated with, endorsed by, or
+sponsored by any of them. The names identify the engines this package is tested against, and those it is not. See [TRADEMARKS.md](./TRADEMARKS.md).
+
 ## License
 
 MIT

package/TRADEMARKS.md

@@ -0,0 +1,30 @@
+# Trademarks
+
+`@cosyte/mllp` is an independent open-source project. cosyte is **not affiliated with, endorsed by,
+or sponsored by** any company named in this repository or its documentation.
+
+## Why these names appear
+
+This package names other systems in two places: to identify the engines its differential test
+harness runs against, and to state plainly which engines it has **not** been verified against.
+
+Every reference is **descriptive**: it identifies whose engine was tested against, or whose behaviour is explicitly not covered. Naming a system is the only way to say
+whether a library works with it.
+
+## How these names are used
+
+This package has no vendor profile system. The names identify freely available software used for
+interoperability testing, or appear in documentation recording the limits of that testing,
+including an explicit statement that Epic and Cerner are **not** part of the harness.
+
+## Names referenced
+
+| Name | Where it appears |
+| ---- | ---------------- |
+| Mirth Connect, NextGen | Named as an engine in the differential test harness. |
+| Google Cloud Healthcare | Named as an engine in the differential test harness (the MLLP adapter). |
+| Epic, Cerner | Named in `docs-content/limitations.md` to record that this package is **not** differentially verified against them. |
+
+All product names, logos, and brands are the property of their respective owners. Use of a name here
+does not imply any affiliation with, or endorsement by, its owner. If you own one of these marks and
+would like a reference changed, please open an issue.

package/dist/ack-from-hl7/index.cjs

@@ -2,7 +2,7 @@
 
 var module$1 = require('module');
 
-// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.10_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
+// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.10_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
@@ -22,13 +22,13 @@ var MllpFramingError = class _MllpFramingError extends Error {
   /**
    * Up to 64 bytes copied from around the anomaly.
    *
-   * This is a **copied** Buffer — isolated from the source buffer so it remains
+   * This is a **copied** Buffer, isolated from the source buffer so it remains
    * valid after the underlying buffer is reused or overwritten.
    *
-   * **PHI contract (MLLP-9):** the decoder only ever populates this with the single
+   * **PHI contract:** the decoder only ever populates this with the single
    * framing-boundary byte that violated the frame structure (whose hex value the
-   * `message` already discloses) — never a run of payload content bytes. For anomalies
-   * whose fault is not a specific byte (`MLLP_FRAME_TOO_LARGE` — the accumulated size),
+   * `message` already discloses), never a run of payload content bytes. For anomalies
+   * whose fault is not a specific byte (`MLLP_FRAME_TOO_LARGE`, the accumulated size),
    * the snippet is **empty**: a payload slice on a public error field would leak a
    * field-body slice of clinical content. Callers constructing this directly are
    * responsible for the same discipline.
@@ -110,9 +110,9 @@ var UNSAFE_FIELD_SEPARATORS = /* @__PURE__ */ new Set([
   SEGMENT_SEPARATOR_CR,
   SEGMENT_SEPARATOR_LF,
   11,
-  // VT — MLLP start block
+  // VT, MLLP start block
   28
-  // FS — MLLP end block
+  // FS, MLLP end block
 ]);
 function isMshSegmentAt(buf, i) {
   return i + 3 < buf.length && buf[i] === ASCII_M && buf[i + 1] === ASCII_S && buf[i + 2] === ASCII_H && !UNSAFE_FIELD_SEPARATORS.has(buf[i + 3]);
@@ -211,7 +211,7 @@ var MllpPeerMissingError = class _MllpPeerMissingError extends Error {
    */
   constructor(cause) {
     super(
-      `${PEER_PACKAGE_NAME} is required by ${SUBPATH_NAME} but is not installed. ${PEER_PACKAGE_NAME} is an optional peer dependency of @cosyte/mllp \u2014 install it alongside @cosyte/mllp to use ${SUBPATH_NAME}: \`npm install ${PEER_PACKAGE_NAME}\` (or the equivalent for your package manager).`,
+      `${PEER_PACKAGE_NAME} is required by ${SUBPATH_NAME} but is not installed. ${PEER_PACKAGE_NAME} is an optional peer dependency of @cosyte/mllp, install it alongside @cosyte/mllp to use ${SUBPATH_NAME}: \`npm install ${PEER_PACKAGE_NAME}\` (or the equivalent for your package manager).`,
       { cause }
     );
     if (Error.captureStackTrace) {
@@ -252,8 +252,16 @@ function loadHl7Peer(requireFn) {
 // src/ack-from-hl7/build.ts
 var MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
 var MLLP_ACK_CONTROL_ID_NOT_VERBATIM = "MLLP_ACK_CONTROL_ID_NOT_VERBATIM";
+var MLLP_ACK_CONTROL_ID_UNVERIFIABLE = "MLLP_ACK_CONTROL_ID_UNVERIFIABLE";
 var BYTES_INBOUND_ENCODING = "latin1";
 var TEXT_INBOUND_ENCODING = "utf8";
+var SERIALIZABLE_ACK_ENCODINGS = /* @__PURE__ */ new Set([
+  "utf8",
+  "utf-8",
+  "ascii",
+  "latin1",
+  "binary"
+]);
 function assertKnownAckCode(peer, code) {
   const known = Object.values(peer.ACK_CODES);
   if (typeof code !== "string" || !known.includes(code)) {
@@ -266,6 +274,12 @@ function resolveEncoding(inbound, options) {
   if (options.encoding !== void 0) return options.encoding;
   return Buffer.isBuffer(inbound) ? BYTES_INBOUND_ENCODING : TEXT_INBOUND_ENCODING;
 }
+function assertSerializableAckEncoding(encoding) {
+  if (SERIALIZABLE_ACK_ENCODINGS.has(encoding.toLowerCase())) return;
+  throw new TypeError(
+    `buildMllpAck: encoding ${JSON.stringify(encoding)} is not a serializable ACK codec. Serializing an ACK to a non-text codec (base64/base64url/hex/utf16le/ucs2) produces a wholesale-garbage frame the receiver cannot parse, on a Buffer inbound it also garbles the inbound decode, so it can never correlate. Use a text codec ("utf8", "ascii", or "latin1"); on a Buffer, "latin1" is byte-verbatim and is the default.`
+  );
+}
 function inboundBytes(inbound, encoding) {
   if (Buffer.isBuffer(inbound)) return inbound;
   if (typeof inbound === "string") return Buffer.from(inbound, encoding);
@@ -281,7 +295,23 @@ function verifyVerbatimEcho(ackPayload, inboundRaw) {
   const echoed = echoedId === null ? "absent" : `${String(echoedId.length)} bytes`;
   return {
     code: MLLP_ACK_CONTROL_ID_NOT_VERBATIM,
-    message: `ACK does not echo the inbound MSH-10 verbatim (HL7 v2.5.1 \xA72.9.2.2): inbound MSH-10 is ${inboundLen} bytes, emitted MSA-2 is ${echoed}, and they differ. The sender keys its in-flight store on the inbound bytes, so it will NOT match this ACK (ACK timeout -> resend -> duplicate message). Field values are withheld \u2014 MSH-10 is inbound payload content and this warning goes to a log; compare your inbound payload against MllpAck.payload to see the bytes.`
+    message: `ACK does not echo the inbound MSH-10 verbatim (HL7 v2.5.1 \xA72.9.2.2): inbound MSH-10 is ${inboundLen} bytes, emitted MSA-2 is ${echoed}, and they differ. The sender keys its in-flight store on the inbound bytes, so it will NOT match this ACK (ACK timeout -> resend -> duplicate message). Field values are withheld, MSH-10 is inbound payload content and this warning goes to a log; compare your inbound payload against MllpAck.payload to see the bytes.`
+  };
+}
+function verifyTextInboundEcho(controlId, inbound) {
+  if (Buffer.isBuffer(inbound)) return null;
+  if (controlId === "") return null;
+  let hasNonAscii = false;
+  for (let i = 0; i < controlId.length; i++) {
+    if (controlId.charCodeAt(i) > 127) {
+      hasNonAscii = true;
+      break;
+    }
+  }
+  if (!hasNonAscii) return null;
+  return {
+    code: MLLP_ACK_CONTROL_ID_UNVERIFIABLE,
+    message: `ACK's byte-verbatim echo of MSH-10 (HL7 v2.5.1 \xA72.9.2.2) cannot be verified: the inbound was decoded text (a string or Hl7Message), not raw bytes, so its wire bytes are gone and the ${String(controlId.length)}-code-unit MSA-2 control ID holds a non-ASCII code unit the decode/encode codec could have altered (a lossy override such as ascii can even mask it into the ASCII byte range). It may not correlate at the sender (ACK timeout -> resend -> duplicate message). Pass the raw payload Buffer to get the byte-level guarantee. Field values are withheld, MSH-10 is inbound payload content and this warning goes to a log.`
   };
 }
 function toMllpAck(params) {
@@ -291,7 +321,13 @@ function toMllpAck(params) {
     allowDelimiterBytesInPayload: options.allowDelimiterBytesInPayload ?? false
   });
   const echoWarning = verifyVerbatimEcho(payload, params.verifyAgainst);
-  const allWarnings = echoWarning === null ? warnings : [...warnings, echoWarning];
+  const echoedControlId = ack.segments("MSA")[0]?.field(2).text ?? "";
+  const unverifiableWarning = params.inbound === void 0 ? null : verifyTextInboundEcho(echoedControlId, params.inbound);
+  const allWarnings = [
+    ...warnings,
+    ...echoWarning === null ? [] : [echoWarning],
+    ...unverifiableWarning === null ? [] : [unverifiableWarning]
+  ];
   const result = {
     frame,
     payload,
@@ -322,11 +358,12 @@ function buildUnparseableFallback(peer, requestedCode, fatalCode, options, encod
     warnings,
     options,
     encoding,
-    // MSA-2 is INTENTIONALLY empty here — the inbound could not be parsed, so there is no
-    // control id to echo and we refuse to fabricate one. Running the verbatim check would
-    // report that deliberate choice as a violation; `MLLP_ACK_INBOUND_UNPARSEABLE` (above)
+    // MSA-2 is INTENTIONALLY empty here, the inbound could not be parsed, so there is no
+    // control id to echo and we refuse to fabricate one. Running either echo check would
+    // report that deliberate choice as a problem; `MLLP_ACK_INBOUND_UNPARSEABLE` (above)
     // is the accurate warning for this case, and it is already attached.
-    verifyAgainst: void 0
+    verifyAgainst: void 0,
+    inbound: void 0
   });
 }
 function resolveInbound(peer, inbound, encoding) {
@@ -343,6 +380,7 @@ function buildMllpAck(inbound, options) {
   const peer = loadHl7Peer();
   assertKnownAckCode(peer, options.code);
   const encoding = resolveEncoding(inbound, options);
+  assertSerializableAckEncoding(encoding);
   let msg;
   try {
     msg = resolveInbound(peer, inbound, encoding);
@@ -374,7 +412,8 @@ function buildMllpAck(inbound, options) {
     warnings,
     options,
     encoding,
-    verifyAgainst: inboundBytes(inbound, encoding)
+    verifyAgainst: inboundBytes(inbound, encoding),
+    inbound
   });
 }
 function buildAckAA(inbound, options) {
@@ -402,6 +441,7 @@ function detectMode(inbound) {
 }
 
 exports.MLLP_ACK_CONTROL_ID_NOT_VERBATIM = MLLP_ACK_CONTROL_ID_NOT_VERBATIM;
+exports.MLLP_ACK_CONTROL_ID_UNVERIFIABLE = MLLP_ACK_CONTROL_ID_UNVERIFIABLE;
 exports.MLLP_ACK_INBOUND_UNPARSEABLE = MLLP_ACK_INBOUND_UNPARSEABLE;
 exports.MllpPeerMissingError = MllpPeerMissingError;
 exports.buildAckAA = buildAckAA;