@cosyte/dicom 0.0.7 → 0.0.10

package/dist/index.d.cts

@@ -2526,13 +2526,21 @@ interface UndefinedVrFinding {
 /**
  * The audit trail returned alongside the de-identified dataset.
  *
- * Every field except one is composed from static tables: tags, Part 6 keywords,
- * Annex E action codes, structural `TAG[index]` sequence paths, and registry
- * warning messages. **`uidMap` is the exception, and it is not value-free.** Its
- * keys are the source UIDs read out of the file, kept so a caller can make UID
- * replacement consistent across a study or an archive. A Study or SOP Instance
- * UID is a unique identifying number, so treat `uidMap` as PHI: the rest of the
- * report is safe to log, and that field is not.
+ * Most fields are composed from static tables: Part 6 keywords, Annex E action
+ * codes, structural `TAG[index]` sequence paths, and registry warning messages.
+ * **Two are not, and both are named here rather than in a footnote.**
+ *
+ * 1. **`uidMap`** - its keys are the source UIDs read out of the file, kept so a
+ *    caller can make UID replacement consistent across a study or an archive. A
+ *    Study or SOP Instance UID is a unique identifying number, so treat it as
+ *    PHI.
+ * 2. **`removedPrivateTags`** - see the field's own note. On a *well-formed*
+ *    file these are the sender's own private tag numbers and carry nothing; on a
+ *    malformed one a tag can be four bytes of a value, and it is measured, not
+ *    theoretical.
+ *
+ * So "the report is safe to log apart from `uidMap`" is **not** an accurate
+ * description of this type, and was corrected rather than kept convenient.
  *
  * @example
  * ```ts
@@ -2545,7 +2553,24 @@ interface UndefinedVrFinding {
 interface DeidentifyReport {
     /** Per-attribute outcomes for every attribute Annex E acted on. */
     readonly attributes: readonly DeidentifiedAttribute[];
-    /** Private tags removed under the Basic Profile (kept ones are omitted). */
+    /**
+     * Private tags removed under the Basic Profile (kept ones are omitted).
+     *
+     * **This is the second field that is not value-free, and the qualification is
+     * measured.** A tag here is composed from four bytes of the source, and on a
+     * file whose Value Lengths disagree with its bytes those four bytes can be
+     * document content rather than a tag the sender wrote: an `OB` carrier holding
+     * `"SECRET-NOTE-"` followed by a well-formed odd-group header reports
+     * `["41534342"]`, whose wire-order bytes read `"SABC"`. That reproduces
+     * identically on every release that has shipped this field.
+     *
+     * It is reported anyway, because *which* private tags were removed is the
+     * whole audit value of the field and withholding them would destroy it on
+     * every well-formed file to bound a malformed one. Narrowing it - to blocks a
+     * creator in the same Data Set actually reserved, say - is a product decision
+     * about audit value versus a four-byte echo, not a defect fix, and it has not
+     * been made. Treat this array as PHI when the source is untrusted.
+     */
     readonly removedPrivateTags: readonly Tag[];
     /**
      * Values emptied because whole Data Elements were encoded inside them by an
@@ -2728,8 +2753,8 @@ declare class DeidentifyError extends Error {
  * nine *metadata-affecting* Annex E Options, driven by the generated Table E.1-1
  * action map ({@link annexE}). It is a **pure** function: the input {@link Dataset}
  * is never mutated; a fresh `Dataset` (with a rebuilt element map and File Meta)
- * is returned alongside a {@link DeidentifyReport} that is value-free except for
- * `uidMap`, whose keys are the file's own source UIDs.
+ * is returned alongside a {@link DeidentifyReport} whose two non-value-free
+ * fields are named on that type: `uidMap` and `removedPrivateTags`.
  *
  * **What it does**
  * - Resolves each attribute's action (basic profile, overridden by an active
@@ -2804,6 +2829,29 @@ declare class DeidentifyError extends Error {
  *   `35adc2d`. No content test can decide it - arbitrary bytes are what those
  *   VRs are for - and the one candidate remedy empties conformant binary values.
  *   See `./embedded.ts`.
+ * - `RetainSafePrivate` **retains nothing inside a Sequence Item whose Data Set
+ *   boundary the file contradicts** - an item stream that ran past its
+ *   sequence's own declared Value Length. Which elements are in the Item is then
+ *   not determined by the file, and PS3.5 §7.8.1 scopes a private block
+ *   reservation to exactly that boundary, so PS3.15 §E.3.10's "known ... to be
+ *   safe" cannot be established and its "all other Private Attributes shall be
+ *   removed **or processed in the element-specific manner recommended by
+ *   Deidentification Action (0008,0307), if present within Private Data Element
+ *   Characteristics Sequence (0008,0300)**" applies - a two-branch clause, of
+ *   which removal is the branch available here (`(0008,0307)` is not
+ *   implemented). Every private element the recursion **reaches** in such an
+ *   Item, at any depth below it, is removed and named in
+ *   `report.removedPrivateTags`. **There is one carve-out, and it is the same one
+ *   `#54` was refused for asserting away**: `keepsPrivate` decides *before* the
+ *   descent, so a **private `SQ`** the profile vouches for is kept **verbatim**,
+ *   its items are never walked, and this rule is never consulted inside it -
+ *   measured, and it still leaks a private value absorbed from the root
+ *   (`PRE-EXISTING`, identical on `164eb39`, its own item). That costs content
+ *   on a malformed file and nothing at all on a conformant one; without it a
+ *   private value the sender wrote **outside** the sequence was retained on the
+ *   Item's reservation and written into output stamped `PatientIdentityRemoved =
+ *   YES` with `removedPrivateTags: []` (`DICOM-PRIVATE-CREATOR-RESERVATION-LEAK`,
+ *   live through `0.0.9`). See {@link itemStreamOverrunsSequence}.
  *
  * @module
  */

package/dist/index.d.ts

@@ -2526,13 +2526,21 @@ interface UndefinedVrFinding {
 /**
  * The audit trail returned alongside the de-identified dataset.
  *
- * Every field except one is composed from static tables: tags, Part 6 keywords,
- * Annex E action codes, structural `TAG[index]` sequence paths, and registry
- * warning messages. **`uidMap` is the exception, and it is not value-free.** Its
- * keys are the source UIDs read out of the file, kept so a caller can make UID
- * replacement consistent across a study or an archive. A Study or SOP Instance
- * UID is a unique identifying number, so treat `uidMap` as PHI: the rest of the
- * report is safe to log, and that field is not.
+ * Most fields are composed from static tables: Part 6 keywords, Annex E action
+ * codes, structural `TAG[index]` sequence paths, and registry warning messages.
+ * **Two are not, and both are named here rather than in a footnote.**
+ *
+ * 1. **`uidMap`** - its keys are the source UIDs read out of the file, kept so a
+ *    caller can make UID replacement consistent across a study or an archive. A
+ *    Study or SOP Instance UID is a unique identifying number, so treat it as
+ *    PHI.
+ * 2. **`removedPrivateTags`** - see the field's own note. On a *well-formed*
+ *    file these are the sender's own private tag numbers and carry nothing; on a
+ *    malformed one a tag can be four bytes of a value, and it is measured, not
+ *    theoretical.
+ *
+ * So "the report is safe to log apart from `uidMap`" is **not** an accurate
+ * description of this type, and was corrected rather than kept convenient.
  *
  * @example
  * ```ts
@@ -2545,7 +2553,24 @@ interface UndefinedVrFinding {
 interface DeidentifyReport {
     /** Per-attribute outcomes for every attribute Annex E acted on. */
     readonly attributes: readonly DeidentifiedAttribute[];
-    /** Private tags removed under the Basic Profile (kept ones are omitted). */
+    /**
+     * Private tags removed under the Basic Profile (kept ones are omitted).
+     *
+     * **This is the second field that is not value-free, and the qualification is
+     * measured.** A tag here is composed from four bytes of the source, and on a
+     * file whose Value Lengths disagree with its bytes those four bytes can be
+     * document content rather than a tag the sender wrote: an `OB` carrier holding
+     * `"SECRET-NOTE-"` followed by a well-formed odd-group header reports
+     * `["41534342"]`, whose wire-order bytes read `"SABC"`. That reproduces
+     * identically on every release that has shipped this field.
+     *
+     * It is reported anyway, because *which* private tags were removed is the
+     * whole audit value of the field and withholding them would destroy it on
+     * every well-formed file to bound a malformed one. Narrowing it - to blocks a
+     * creator in the same Data Set actually reserved, say - is a product decision
+     * about audit value versus a four-byte echo, not a defect fix, and it has not
+     * been made. Treat this array as PHI when the source is untrusted.
+     */
     readonly removedPrivateTags: readonly Tag[];
     /**
      * Values emptied because whole Data Elements were encoded inside them by an
@@ -2728,8 +2753,8 @@ declare class DeidentifyError extends Error {
  * nine *metadata-affecting* Annex E Options, driven by the generated Table E.1-1
  * action map ({@link annexE}). It is a **pure** function: the input {@link Dataset}
  * is never mutated; a fresh `Dataset` (with a rebuilt element map and File Meta)
- * is returned alongside a {@link DeidentifyReport} that is value-free except for
- * `uidMap`, whose keys are the file's own source UIDs.
+ * is returned alongside a {@link DeidentifyReport} whose two non-value-free
+ * fields are named on that type: `uidMap` and `removedPrivateTags`.
  *
  * **What it does**
  * - Resolves each attribute's action (basic profile, overridden by an active
@@ -2804,6 +2829,29 @@ declare class DeidentifyError extends Error {
  *   `35adc2d`. No content test can decide it - arbitrary bytes are what those
  *   VRs are for - and the one candidate remedy empties conformant binary values.
  *   See `./embedded.ts`.
+ * - `RetainSafePrivate` **retains nothing inside a Sequence Item whose Data Set
+ *   boundary the file contradicts** - an item stream that ran past its
+ *   sequence's own declared Value Length. Which elements are in the Item is then
+ *   not determined by the file, and PS3.5 §7.8.1 scopes a private block
+ *   reservation to exactly that boundary, so PS3.15 §E.3.10's "known ... to be
+ *   safe" cannot be established and its "all other Private Attributes shall be
+ *   removed **or processed in the element-specific manner recommended by
+ *   Deidentification Action (0008,0307), if present within Private Data Element
+ *   Characteristics Sequence (0008,0300)**" applies - a two-branch clause, of
+ *   which removal is the branch available here (`(0008,0307)` is not
+ *   implemented). Every private element the recursion **reaches** in such an
+ *   Item, at any depth below it, is removed and named in
+ *   `report.removedPrivateTags`. **There is one carve-out, and it is the same one
+ *   `#54` was refused for asserting away**: `keepsPrivate` decides *before* the
+ *   descent, so a **private `SQ`** the profile vouches for is kept **verbatim**,
+ *   its items are never walked, and this rule is never consulted inside it -
+ *   measured, and it still leaks a private value absorbed from the root
+ *   (`PRE-EXISTING`, identical on `164eb39`, its own item). That costs content
+ *   on a malformed file and nothing at all on a conformant one; without it a
+ *   private value the sender wrote **outside** the sequence was retained on the
+ *   Item's reservation and written into output stamped `PatientIdentityRemoved =
+ *   YES` with `removedPrivateTags: []` (`DICOM-PRIVATE-CREATOR-RESERVATION-LEAK`,
+ *   live through `0.0.9`). See {@link itemStreamOverrunsSequence}.
  *
  * @module
  */

package/dist/index.mjs

@@ -9,7 +9,7 @@ var __export = (target, all) => {
 };
 
 // src/version.ts
-var VERSION = "0.0.7";
+var VERSION = "0.0.10";
 
 // src/dictionary/index.ts
 var dictionary_exports = {};
@@ -11701,6 +11701,12 @@ var BE_VR_STRIDE = Object.freeze({
   UT: 0,
   SQ: 0
 });
+var KNOWN_VRS = Object.freeze(
+  new Set(Object.keys(BE_VR_STRIDE))
+);
+function isRecognizedVr(vr) {
+  return KNOWN_VRS.has(vr);
+}
 
 // src/parser/warnings.ts
 var WARNING_CODES = {
@@ -11751,7 +11757,11 @@ var WARNING_MESSAGES = Object.freeze({
   DICOM_VR_MISMATCH: "Element ({tag}) on-wire VR is {vr2}; dictionary lists {vr}. Trusting on-wire VR.",
   DICOM_PRIVATE_TAG_NO_CREATOR: "Private element ({tag}) has no Private Creator registered for its block; treating as VR=UN.",
   DICOM_GROUP_LENGTH_IN_DATASET: "Retired Group Length element ({tag}) encountered in dataset; preserved as-is.",
-  DICOM_NONZERO_RESERVED_BYTES: "Element ({tag}) has non-zero reserved bytes between VR and length (first byte {n}, second byte {n2}); ignoring.",
+  // The tag is deliberately absent, and this is the only *parser* message where
+  // that is true. See `nonzeroReservedBytes`. Kept terse for the same reason the
+  // de-identify messages are: it is emitted once per element, and element count
+  // is attacker-chosen.
+  DICOM_NONZERO_RESERVED_BYTES: "Non-zero reserved bytes between VR and length (first byte {n}, second byte {n2}); ignoring. Tag withheld; the byte offset identifies the element.",
   DICOM_SQ_NOT_DESCENDED: "Element ({tag}) resolved to VR=SQ from the dictionary but its defined-length value is not a valid item stream; kept as opaque bytes and NOT descended, so nothing nested inside it is visible to navigation, and deidentify() cannot audit it. See DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE.",
   DICOM_UN_PARSED_AS_SQ: "Element ({tag}) has VR=UN with undefined length; descended as Implicit VR LE sequence per CP-246.",
   DICOM_EMPTY_ITEM_IN_SEQUENCE: "Sequence ({tag}) contains an empty item (length=0); tolerated.",
@@ -11786,7 +11796,6 @@ var WARNING_MESSAGES = Object.freeze({
   DICOM_UNSUPPORTED_CHARSET: "(0008,0005) Specific Character Set value {n} names a defined term this build does not support; decoding text as UTF-8 best-effort. The term is not reproduced here - read the element if you need it.",
   DICOM_CHARSET_AMBIGUOUS_SEPARATOR: "(0008,0005) Specific Character Set value {n} is ambiguous under the active code extensions; decoding text as UTF-8 best-effort."
 });
-var KNOWN_VRS = new Set(Object.keys(BE_VR_STRIDE));
 var TAG_SHAPE = /^[0-9A-F]{8}$/u;
 function renderTag(tag) {
   return tag !== void 0 && TAG_SHAPE.test(tag) ? tag : WITHHELD;
@@ -11828,9 +11837,8 @@ function privateTagNoCreator(position, tag) {
 function groupLengthInDataset(position, tag) {
   return build(WARNING_CODES.DICOM_GROUP_LENGTH_IN_DATASET, position, { tag });
 }
-function nonzeroReservedBytes(position, tag, first, second) {
+function nonzeroReservedBytes(position, first, second) {
   return build(WARNING_CODES.DICOM_NONZERO_RESERVED_BYTES, position, {
-    tag,
     n: first,
     n2: second
   });
@@ -12034,12 +12042,12 @@ function readExplicitElementHeader(cursor, _ctx, emit) {
   const vr = vrSlice.toString("ascii");
   let length;
   let headerLength;
-  if (LONG_FORM_VRS.has(vr)) {
+  if (LONG_FORM_VRS.has(vr) || !isRecognizedVr(vr)) {
     const reserved0 = cursor.buffer[cursor.position];
     const reserved1 = cursor.buffer[cursor.position + 1];
     cursor.position += 2;
     if ((reserved0 ?? 0) !== 0 || (reserved1 ?? 0) !== 0) {
-      emit(nonzeroReservedBytes({ byteOffset: headerStart }, tag, reserved0 ?? 0, reserved1 ?? 0));
+      emit(nonzeroReservedBytes({ byteOffset: headerStart }, reserved0 ?? 0, reserved1 ?? 0));
     }
     length = cursor.readUInt32();
     headerLength = 12;
@@ -12177,7 +12185,7 @@ function readExplicitLeElement(cursor) {
   const vr = cursor.slice(2).toString("ascii");
   let length;
   let headerLength;
-  if (LONG_FORM_VRS.has(vr)) {
+  if (LONG_FORM_VRS.has(vr) || !isRecognizedVr(vr)) {
     cursor.slice(2);
     length = cursor.readUInt32();
     headerLength = 12;
@@ -13451,7 +13459,7 @@ function encodeDatasetElement(el, encoding) {
   }
   const littleEndian = encoding === "explicitLE";
   const vrBuf = Buffer.from(el.vr, "ascii");
-  if (LONG_FORM_VRS.has(el.vr)) {
+  if (LONG_FORM_VRS.has(el.vr) || !isRecognizedVr(el.vr)) {
     return Buffer.concat([
       uint16(group, littleEndian),
       uint16(element, littleEndian),
@@ -13502,7 +13510,7 @@ function encodeMetaElement(tag, vr, rawValue) {
   const elementBuf = Buffer.alloc(2);
   elementBuf.writeUInt16LE(element, 0);
   const vrBuf = Buffer.from(vr, "ascii");
-  if (LONG_FORM_VRS.has(vr)) {
+  if (LONG_FORM_VRS.has(vr) || !isRecognizedVr(vr)) {
     const lengthBuf2 = Buffer.alloc(4);
     lengthBuf2.writeUInt32LE(value.length, 0);
     return Buffer.concat([
@@ -14697,7 +14705,6 @@ function uidValueMultiplicity(rawBytes) {
 }
 
 // src/deident/embedded.ts
-var KNOWN_VRS2 = new Set(Object.keys(BE_VR_STRIDE));
 var UNDEFINED_LENGTH4 = 4294967295;
 var FFFE_GROUP = 65534;
 var SCANNABLE_CARRIER_VRS = /* @__PURE__ */ new Set([
@@ -14758,7 +14765,7 @@ function decodeAt(value, off, encoding) {
     return next2 > value.length ? void 0 : { next: next2, tag };
   }
   const vr = value.toString("latin1", off + 4, off + 6);
-  if (!KNOWN_VRS2.has(vr)) return void 0;
+  if (!KNOWN_VRS.has(vr)) return void 0;
   if (LONG_FORM_VRS.has(vr)) {
     if (off + 12 > value.length) return void 0;
     if (value[off + 6] !== 0 || value[off + 7] !== 0) return void 0;
@@ -14895,7 +14902,6 @@ var BODY_ENCODING2 = {
 };
 var MAX_UNAUDITABLE_SEQUENCE_FINDINGS = 64;
 var MAX_UNDEFINED_VR_FINDINGS = 64;
-var KNOWN_VRS3 = new Set(Object.keys(BE_VR_STRIDE));
 function validateRetain(retain) {
   const valid = new Set(DEIDENTIFY_OPTIONS);
   const active = /* @__PURE__ */ new Set();
@@ -15016,7 +15022,7 @@ function actsOnTag(tag, ctx) {
   return resolveAction(effectiveCode(action, ctx.active)) !== "K";
 }
 function hasUndefinedVr(el) {
-  return !KNOWN_VRS3.has(el.vr);
+  return !KNOWN_VRS.has(el.vr);
 }
 function keepOrEmpty(el, ctx, contextPath, out) {
   if (hasUndefinedVr(el)) {
@@ -15080,6 +15086,13 @@ function creatorFor(tag, creators) {
   const { group, element } = splitTag(tag);
   return creators.get(`${String(group)}:${String(element >> 8 & 255)}`);
 }
+var UNDEFINED_LENGTH5 = 4294967295;
+var EXPLICIT_SQ_HEADER_BYTES = 12;
+function itemStreamOverrunsSequence(el, encoding) {
+  if (el.vr !== "SQ" || el.length === UNDEFINED_LENGTH5) return false;
+  const headerBytes = encoding === "implicit" ? 0 : EXPLICIT_SQ_HEADER_BYTES;
+  return el.rawBytes.length - headerBytes > el.length;
+}
 function keepsPrivate(el, ctx, creators) {
   if (!ctx.active.has("RetainSafePrivate") || ctx.profile === void 0) return false;
   if (isPrivateCreatorElement(el.tag)) {
@@ -15089,7 +15102,7 @@ function keepsPrivate(el, ctx, creators) {
   if (creator === void 0) return false;
   return resolvePrivateTag(ctx.profile, el.tag, creator) !== void 0;
 }
-function processElements(source, ctx, contextPath) {
+function processElements(source, ctx, contextPath, reservationsUsable) {
   const out = {
     elements: /* @__PURE__ */ new Map(),
     attributes: [],
@@ -15102,7 +15115,8 @@ function processElements(source, ctx, contextPath) {
   const creators = creatorsInScope(source);
   for (const el of source) {
     if (isPrivateTag(el.tag)) {
-      if (keepsPrivate(el, ctx, creators)) keepOrEmpty(el, ctx, contextPath, out);
+      if (reservationsUsable && keepsPrivate(el, ctx, creators))
+        keepOrEmpty(el, ctx, contextPath, out);
       else out.removedPrivateTags.push(el.tag);
       continue;
     }
@@ -15110,7 +15124,8 @@ function processElements(source, ctx, contextPath) {
     if (action === void 0) {
       if (el.vr === "SQ") {
         if (isUnauditableSequence(el)) emptyUnauditableSequence(el, ctx, contextPath, out);
-        else out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
+        else
+          out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out, reservationsUsable));
       } else {
         keepOrEmpty(el, ctx, contextPath, out);
       }
@@ -15118,7 +15133,7 @@ function processElements(source, ctx, contextPath) {
     }
     const resolved = resolveAction(effectiveCode(action, ctx.active));
     if (el.vr === "SQ") {
-      applySequenceAction(el, resolved, action, ctx, contextPath, out);
+      applySequenceAction(el, resolved, action, ctx, contextPath, out, reservationsUsable);
       continue;
     }
     let applied;
@@ -15159,11 +15174,12 @@ function processElements(source, ctx, contextPath) {
   }
   return out;
 }
-function descendSequence(el, ctx, contextPath, out) {
+function descendSequence(el, ctx, contextPath, out, reservationsUsable) {
+  const childReservationsUsable = reservationsUsable && !itemStreamOverrunsSequence(el, ctx.encoding);
   const newItems = [];
   (el.items ?? []).forEach((item, index) => {
     const childPath = [...contextPath, `${el.tag}[${String(index)}]`];
-    const inner = processElements(item.elements(), ctx, childPath);
+    const inner = processElements(item.elements(), ctx, childPath, childReservationsUsable);
     out.attributes.push(...inner.attributes);
     out.removedPrivateTags.push(...inner.removedPrivateTags);
     out.embeddedAttributes.push(...inner.embeddedAttributes);
@@ -15174,7 +15190,7 @@ function descendSequence(el, ctx, contextPath, out) {
   });
   return rebuildSequence(el, newItems, ctx.encoding);
 }
-function applySequenceAction(el, resolved, action, ctx, contextPath, out) {
+function applySequenceAction(el, resolved, action, ctx, contextPath, out, reservationsUsable) {
   let applied;
   switch (resolved) {
     case "X":
@@ -15190,7 +15206,7 @@ function applySequenceAction(el, resolved, action, ctx, contextPath, out) {
         emptyUnauditableSequence(el, ctx, contextPath, out);
         applied = "emptied";
       } else {
-        out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
+        out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out, reservationsUsable));
         applied = "cleaned";
       }
       break;
@@ -15200,7 +15216,7 @@ function applySequenceAction(el, resolved, action, ctx, contextPath, out) {
         emptyUnauditableSequence(el, ctx, contextPath, out);
         applied = "emptied";
       } else {
-        out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
+        out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out, reservationsUsable));
         applied = "kept";
       }
       break;
@@ -15251,7 +15267,7 @@ function deidentify(ds, options = {}) {
     encoding,
     budget: { unauditableSequences: 0, undefinedVrElements: 0 }
   };
-  const processed = processElements(ds.elements(), ctx, []);
+  const processed = processElements(ds.elements(), ctx, [], true);
   const {
     elements,
     attributes,