@cosyte/mllp 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -76,6 +76,52 @@ begins its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` unt
 
 ### Security
 
+- **BREAKING: ACK-correlation diagnostics no longer carry the control ID (`PHI-WARNING-MESSAGE-LEAK`).**
+  The opt-in `correlateByControlId` path built its diagnostics by interpolation, and both ends were
+  consumer-controlled and unbounded. The unmatched-ACK path read the **peer's** MSA-2 straight off an
+  inbound frame into `MllpFramingError.message` and onto a `controlId` field of the frozen `'error'`
+  payload; measured against a peer sending a 1,000,000-byte MSA-2, that produced a 1,000,026-byte
+  `Error.message` and an equally large event field, both headed for a log. `MLLP_ACK_AFTER_TIMEOUT`
+  did the same with the timed-out send's own MSH-10, and `MllpTimeoutError.messageControlId` carried
+  it on an `Error`, whose `stack` is what an error reporter ships off the box.
+  The fix is the frozen-registry shape: `src/client/ack-diagnostics.ts` holds one literal per code and
+  `ackDiagnosticMessage(code)` takes **no value parameter**, so no caller can widen it into an
+  interpolation site. The `Correlator` withholds the string at the source: `onWarning` now receives
+  `controlIdBytes` and `onUnmatchedAck` receives a byte length (or `null` when no MSA-2 could be read
+  at all), so nothing downstream of it has a control ID to interpolate.
+  Breaking field changes, all pre-alpha: `MllpTimeoutError.messageControlId: string | undefined` is
+  now `messageControlIdBytes: number | undefined`; the `'error'` event's `controlId` is now
+  `controlIdBytes`; the `'warning'` payload for the two correlation codes is the new exported
+  `AckCorrelationWarning` (`MllpWarning` plus `controlIdBytes` and `elapsedSinceSendMs`). Warning
+  codes are unchanged. A truncated ID was considered and rejected, as was a hex rendering: both still
+  grow the diagnostic with the input and both still disclose the bytes. This is the same answer the
+  ACK adapter's verbatim-echo warning already reached.
+- **A diagnostic-surface PHI gate that instantiates a client (`test/phi/diagnostic-phi-leak.test.ts`).**
+  Binds the shared `assertNoDiagnosticPhiLeak` runner (`@cosyte/test-utils`, pin raised to `^0.0.2`;
+  a caret on a `0.0.x` version resolves to that version exactly, so without the bump the runner is not
+  even installed). Nineteen declared slots, each naming the diagnostic code it must reach, covering
+  the message control ID through correlation, an ACK's own MSH-10 and MSA-3, the outbound payload
+  body, embedded VT and FS bytes inbound and outbound, an oversized frame, missing leading VT,
+  leading whitespace, FS without CR, LF after FS, an empty payload after a marker-bearing frame, the
+  in-flight orphan on disconnect, and all three of the ACK adapter's control-ID paths (unparseable
+  inbound, a provably non-verbatim echo, and an unverifiable text echo). The suite it supplements
+  scoped itself to the framing layer and never instantiated a client, which is exactly why the three
+  correlation surfaces were the three it could not reach. Verified red on the base commit on three
+  slots before any fix existed, and re-verified by four mutations afterwards, one of which is a
+  hex-encoded echo that a verbatim match cannot see and `checkLengthInvariance` catches.
+  `checkLengthInvariance` is decided **per slot and by measurement**: 8 of the 19 hold it, and the
+  other 11 give it up because a byte offset or a byte count is the prescribed report there and
+  growth is correct. A first draft split the table in two by argument and was wrong about four
+  slots, which were giving up the re-encoded-echo check for nothing.
+  Scope, stated precisely rather than generously: this closes **unbounded** consumer-controlled input
+  on the `correlateByControlId` path. The slot table covers three surfaces (the client, framing via
+  `Connection`, and `ack-from-hl7`) and **no slot instantiates `MllpServer`**; the server's diagnostic
+  surfaces were read and carry static strings, counts, or Node's own TLS and socket text, so that gap
+  holds no HL7 payload today, which is why it was not urgent rather than why the table is complete.
+  Two framing codes still render the hex of a **single** byte, and
+  `MllpFramingError.snippet` still carries one, both bounded by design and both now described
+  accurately on `MllpWarning.message` (whose doc comment claimed the opposite, and shipped that claim
+  into the published declarations).
 - **Repo-side PHI commit-scanner (`scripts/phi-scan.ts`), matching the `@cosyte/hl7` pilot.**
   mllp transports HL7 v2 payloads (MLLP wraps HL7 in `VT … FS CR`), so its data fixtures
   (`test/**` `.frame.bin` frames) carry the same PHI shapes hl7's do. The scanner is a direct
@@ -110,6 +156,26 @@ begins its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` unt
   `InMemoryTransport.pair()`; the receive example's fictional `respond`/`buildAck` → the real
   `createServer({ onMessage })`). Bumps the `@cosyte/vitest-config` devDependency to `^0.0.2` for the
   `/snippets` export. Docs and tests only: no runtime or public-API change.
+- **README header swapped from the per-package banner to the shared Cosyte lockup.** Both sides of
+  this swap happened inside one unreleased window, so no published version carries the banner and
+  the release notes for this version describe only the lockup. It is recorded here, where build
+  history belongs, rather than dropped. The banner
+  (`cosyte-banner-mllp-1200x300.png`) baked the package name and its one line summary into the
+  artwork, and the `# @cosyte/mllp` H1 and the blockquote directly beneath it repeat both, so the
+  same two strings appeared three times in the first four lines of the page. The header is now a
+  `<picture>` carrying the theme-aware Cosyte lockup tile (`cosyte-lockup-tile-on-dark-1200x300.png`
+  and its `-on-light` counterpart), which reads "Cosyte" rather than the package name, so the
+  duplication goes and the heading stays untouched. The `<picture>` element was deliberately avoided
+  when the banner landed, on the grounds that npm sanitizer behaviour was unverified; that has since
+  been verified rather than assumed. On GitHub in dark mode `currentSrc` resolves to the on-dark tile
+  with parent element `PICTURE`, and on npm the `<img>` is hoisted out of the `<picture>` by GitHub's
+  anchor wrapper so the light fallback renders, which is the correct cut there because npmjs.com has
+  no dark mode. The block was copied programmatically out of `hl7`'s README rather than retyped, and
+  both URLs were fetched live (`200 image/png`) rather than trusted from the stored
+  `published-urls.json` declaration, since a typo in either is a 404 on a public package page. The
+  alt text now describes the artwork rather than the package, because a screen reader on the npm page
+  should hear what the image is and the package summary is already the next line. Docs only: no
+  runtime or public-API change.
 - **`docs-content/installation.md` publish-status note corrected (README-ORG-SWEEP).** The Status
   callout said the package was "not yet published to npm" and that the install command was "the shape
   it will take at first publish": stale now that `@cosyte/mllp` is published on npm at `0.0.1` and

package/README.md

@@ -1,3 +1,8 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png">
+  <img alt="Cosyte: a plus mark set in two overlapping rounded squares, one solid and one outlined, beside the Cosyte wordmark" src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
+</picture>
+
 # @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.
@@ -23,8 +28,15 @@ pnpm add @cosyte/mllp
 ```ts
 import { createStarterServer } from "@cosyte/mllp";
 
-// Echoes every received frame straight back as the ACK.
-const server = await createStarterServer({ port: 2575, onMessage: (buf) => buf });
+// Auto-ACK is on by default: the server awaits your handler (the durable-commit
+// step) before it answers, so a positive ACK can never precede the commit.
+// A throw answers a negative ACK instead.
+const server = await createStarterServer({
+  port: 2575,
+  onMessage: async (payload) => {
+    await db.commit(payload);
+  },
+});
 ```
 
 ```ts
@@ -48,7 +60,7 @@ const server = createServer({ tls: { cert: certPem, key: keyPem } });
 await server.listen(2575, "127.0.0.1");
 
 // Server: mutual TLS (ATNA ITI-19)
-const server = createServer({
+const mutualTlsServer = createServer({
   tls: { cert: certPem, key: keyPem, ca: clientCaPem, clientAuth: "MUST" },
 });
 ```
@@ -58,7 +70,7 @@ const server = createServer({
 const client = createClient({ host: "mllp.example.com", port: 2575, tls: { ca: caPem } });
 
 // Client: mutual TLS
-const client = createClient({
+const mutualTlsClient = createClient({
   host: "mllp.example.com",
   port: 2575,
   tls: { ca: caPem, cert: clientCertPem, key: clientKeyPem },
@@ -84,7 +96,11 @@ const server = createServer({
 });
 ```
 
-Handler resolves ⇒ `AA`. Handler throws ⇒ `AE` (or `AR` via `MllpAckError`). **A positive ACK cannot
+Handler resolves ⇒ `AA`, **unless the inbound could not carry a correlatable positive ACK** (no
+readable `MSH`, an empty `MSH-10`, a batch or concatenated payload, or trailing bytes the framer
+discarded). In that case the commit still happened, but the ACK is downgraded to `AE` and a `nack`
+event names the reason, because a positive ACK the sender cannot match is one it will resend.
+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".