Audit and provenance

Generated documents are often corrected in Word before they are filed. For audits, it helps to know which template and data produced a file, whether it changed after generation, and what changed.

Provenance in every document

Every document records, in its custom properties:

Property	Content
`ReactDocx.Template`	Template name, with `renderTemplate`
`ReactDocx.TemplateVersion`	The template’s `version`
`ReactDocx.DataHash`	SHA-256 of the validated data
`ReactDocx.Version`	React DOCX version
`ReactDocx.ContentHash`	SHA-256 of the generated content

Word shows them in File > Properties > Custom. The data hash lets you prove which data produced a document without storing the data in it: hash the stored input again and compare. Your own properties go in customProperties.

Reading it back

The audit functions are in a separate entry point:

import { diffDocx, readProvenance, readRevisions, verifyDocx } from "@cordel/react-docx/audit";

const bytes = await readFile("report.docx");
const { template, templateVersion, dataHash } = readProvenance(bytes);

Was it changed?

const { status } = await verifyDocx(bytes);
// "unchanged" | "modified" | "unknown"

unchanged: the content is exactly what React DOCX generated
modified: saved again after generation. Opening and saving in Word counts, even without edits
unknown: no content hash; not generated by React DOCX, or the property was removed

This detects changes; it does not prove authenticity, since anyone can recompute the hash. For that, sign the file or its PDF.

What changed?

diffDocx compares the paragraphs of two versions, typically the generated file and the corrected one:

for (const change of diffDocx(generated, corrected)) {
  if (change.kind === "changed") console.log(change.before, "→", change.after);
}

Each change is added, removed or changed, with the paragraph texts and their positions. Only text is compared: formatting changes and differences in how programs write the XML do not count. Tracked changes count as accepted.

Who changed it?

With trackChanges, Word records each edit with author and date. readRevisions lists them:

for (const r of readRevisions(corrected)) {
  console.log(r.kind, r.author, r.date, r.text);
}

Each revision is an insertion, deletion or formatting change, with the part it is in (body, header, footer, footnotes) and the text of its paragraph.

Reproducing a document

Output is deterministic: the same template version, data and React DOCX version produce the same file, byte for byte. Store the input data with the document, and the provenance tells you which template version to run to generate it again.

​Provenance in every document

​Reading it back

​Was it changed?

​What changed?

​Who changed it?

​Reproducing a document