JudsonRhodes1569

Posted on Oct 2

Node.js Stored PDF Template vs Repository HTML (Who Signs Off)

#node #pdf #observability

A signed monthly property report has a stricter constraint than a normal web page: six months later, an auditor must be able to identify exactly what was rendered, approved, signed, and archived. TL;DR: keep layout source in the repository when engineers own deterministic releases; use a stored PDF template when document operations must change approved fields independently. In either case, name one layout owner and bind an immutable layout revision, canonical input digest, renderer build, signature result, and archive object into one evidence record. The file format is secondary. The evidence chain decides ownership.

The before/after mental model is short. Before: "the PDF in object storage is the record." After: "the PDF plus the reproducible facts around it are the record." That shift catches the dangerous gap in both approaches: a repository commit can prove source history but not which artifact ran, while a stored template ID can identify a resource but not who approved its contents.

Should a stored PDF template or repository HTML own the layout?

A monthly report may combine rent collected, open maintenance work, reserve balances, and a manager approval. Once a signature is applied, the byte-level document becomes consequential. Changing a label, page break, or signature rectangle after approval is no longer a cosmetic edit to tomorrow's output. It creates a different document that needs its own traceable revision.

PDF defines the document container. ISO 32000-2 is the PDF 2.0 specification, while ETSI EN 319 142 describes PAdES digital signatures for PDF documents. Those standards help define interoperable files and signatures. They do not assign responsibility inside your team.

That responsibility should follow the release boundary. Repository HTML usually puts layout review, tests, and deployment beside application code. This fits a team where engineers control report changes and can ship them through the same review process as calculations. A stored PDF template moves the editable layout behind a document-management boundary. That fits a workflow where compliance or document operations must approve field placement without waiting for an application release.

There is a sharp rule here: the team allowed to publish a layout revision owns the layout, and the service generating the report owns recording which revision it used. Avoid shared, informal ownership. Two groups editing one "current" template produces a clean-looking PDF and a muddy audit trail.

Decision signal	Repository HTML	Stored PDF template
Release authority	Engineering review and deployment	Controlled template publication
Natural change unit	Commit plus built artifact	Immutable template revision
Best fit	Flowing tables and conditional sections	Fixed fields on an approved form
Main audit risk	Commit differs from deployed artifact	Mutable alias hides the exact revision
Required evidence	Commit, build digest, renderer build	Template digest, publication approval, renderer build

Neither column wins by default. A twelve-page report with variable maintenance notes behaves differently from a fixed owner certification page. A hybrid can be reasonable too: render the flowing report from repository HTML, attach a controlled signature page, then sign the combined PDF. The evidence record must identify both layout inputs.

This is the trade-off.

Repository HTML is not suitable when non-engineering approvers must position fields and publish a controlled revision without an application deployment. Its downside is that a tiny wording correction inherits the code release process, and its commit history still cannot prove that the corresponding build produced a particular PDF. A stored template has the opposite limitation: it is a poor fit for long, fluid tables when its editing model assumes fixed fields, and a mutable template alias can hide a change from the application repository. The hybrid has an integration cost of its own. Assembly order, page numbering, font embedding, and the final signature boundary all need tests. These are concrete operational costs, so the ownership decision should name which team accepts them rather than pretending one format removes them.

Build the evidence envelope before rendering

The copyable example below uses Node.js and generic interfaces. It does not prescribe a renderer, signer, or archive. The important part is the order: resolve immutable inputs, canonicalize the report data, render, hash the exact bytes, sign those bytes, archive the signed result, and emit one completion event.

JSON object property order is not a sufficient canonicalization rule for cross-system evidence. RFC 8785 defines the JSON Canonicalization Scheme, including deterministic property sorting and serialization constraints. Use a conforming implementation at every producer boundary; do not replace it with a casual JSON.stringify convention and call the result portable.

import { createHash, randomUUID } from "node:crypto";

type LayoutRef =
  | { kind: "repository-html"; commit: string; artifactSha256: string }
  | { kind: "stored-pdf"; revision: string; templateSha256: string };

type MonthlyReport = {
  propertyId: string;
  period: string;
  rentCollectedCents: number;
  openWorkOrders: number;
  approvedBy: string;
};

type EvidenceRecord = {
  reportId: string;
  layout: LayoutRef;
  inputSha256: string;
  rendererBuild: string;
  unsignedPdfSha256: string;
  signedPdfSha256: string;
  signatureProfile: string;
  archiveKey: string;
  completedAt: string;
};

interface Dependencies {
  canonicalize(value: unknown): Uint8Array;
  render(input: MonthlyReport, layout: LayoutRef): Promise<Uint8Array>;
  sign(pdf: Uint8Array): Promise<{ pdf: Uint8Array; profile: string }>;
  archive(key: string, pdf: Uint8Array, metadata: EvidenceRecord): Promise<void>;
  emit(name: "report.archived", evidence: EvidenceRecord): Promise<void>;
}

const sha256 = (bytes: Uint8Array): string =>
  createHash("sha256").update(bytes).digest("hex");

export async function generateMonthlyReport(
  input: MonthlyReport,
  layout: LayoutRef,
  rendererBuild: string,
  deps: Dependencies,
): Promise<EvidenceRecord> {
  const reportId = randomUUID();
  const inputSha256 = sha256(deps.canonicalize(input));
  const unsignedPdf = await deps.render(input, layout);
  const signed = await deps.sign(unsignedPdf);
  const archiveKey = `monthly-reports/${input.propertyId}/${input.period}/${reportId}.pdf`;

  const evidence: EvidenceRecord = {
    reportId,
    layout,
    inputSha256,
    rendererBuild,
    unsignedPdfSha256: sha256(unsignedPdf),
    signedPdfSha256: sha256(signed.pdf),
    signatureProfile: signed.profile,
    archiveKey,
    completedAt: new Date().toISOString(),
  };

  await deps.archive(archiveKey, signed.pdf, evidence);
  await deps.emit("report.archived", evidence);
  return evidence;
}

One detail matters more than it looks: the archive key contains a unique report ID rather than latest.pdf. Retry the workflow with the same business input only under an explicit idempotency policy. Do not silently overwrite an already signed report. An amendment should create a new record that points to the superseded report, preserving both objects and the reason for change.

The completedAt value records application time; it is not proof from an independent time authority. If the audit policy requires trusted time, RFC 3161 defines a Time-Stamp Protocol in which a time-stamping authority returns a token for a message imprint. Record that token or its durable reference as part of the signature evidence. Be precise. A wall-clock string cannot make the same claim.

Observe the document as a transaction

A render endpoint returning success is weak evidence. The workflow has stages, and each stage can fail independently: layout resolution, data validation, rendering, signing, archival storage, and evidence emission. Model the report as one transaction with a stable reportId; propagate it through logs and traces without placing tenant names, addresses, or approval identities in telemetry.

Rendering is only the midpoint.

OpenTelemetry's logs data model supports trace and span identifiers for correlation. W3C Trace Context defines traceparent and tracestate headers for distributed tracing. Those mechanisms help connect the render operation to signing and archival calls, but the business evidence record should remain durable even if telemetry retention expires. Observability explains execution. It is not the archive.

Useful metrics answer narrow operational questions: completion count by outcome, duration by stage, signature failures by profile, and archive-write failures. Keep property identifiers out of metric labels; high-cardinality identifiers belong in sampled traces or access-controlled logs. Alert on a sustained absence of completed monthly reports near the scheduled reporting window and on any archive integrity mismatch. A raw render-latency alert alone misses the nastier case: fast generation followed by failed archival.

Log transitions, not paragraphs. A completion event can carry reportId, layout kind, immutable revision, renderer build, input digest, signed output digest, signature profile, archive key, duration, and outcome. Never log the report data itself just to make debugging convenient.

This also gives the team a crisp deployment check. Before releasing a renderer build, generate the same fixture twice in a controlled environment, inspect the visual diff, verify required fields and signature placement, and validate the resulting PDF with an independent parser. Exact byte equality may be inappropriate if timestamps or signature material legitimately vary, so test deterministic intermediate artifacts separately from signed output.

What if operations needs same-day copy changes?

Then repository ownership may impose the wrong queue. A stored template can create a controlled publication path for document operations, provided every published revision is immutable, approved, retrievable, and referenced by digest. The application should reject a floating alias such as current at generation time or resolve it once and persist the resulting immutable revision before rendering.

Speed does not erase separation of duties. The person editing payment instructions should not be able to approve and publish the same revision when policy requires independent approval. Likewise, an engineer should not bypass the template publication history by uploading a corrected file directly to production storage. These are governance decisions expressed as permissions and records, not renderer features.

No hidden handoff.

Repository HTML can still support urgent work through a documented review path and a small release unit. Stored templates can still receive automated checks. Run fixture data through every candidate revision, assert required phrases and field bounds, render long names and zero-activity months, and compare pages visually. The format changes the control surface, not the need for tests.

The harder objection is that HTML handles flowing content better while the signature page demands fixed coordinates. Treat that as two layout domains. Generate the variable section, assemble it with the controlled fixed page, and sign only after assembly. Record the repository artifact digest and stored-template digest in the same envelope.

A practical ownership decision

Choose repository HTML when layout changes are application releases, dynamic pagination is central, and engineering can own review and rollback. Choose a stored PDF template when an approved form is the governing artifact and a document team needs a controlled publication lifecycle. Choose a hybrid when the report body and certification page genuinely have different authorities.

Then test the decision with five questions:

Who can publish a new layout, and who independently approves it?
Can an auditor retrieve the exact immutable layout revision for one archived PDF?
Does the evidence identify canonical input, renderer build, unsigned digest, signed digest, and signature profile?
Can an amendment preserve the original while linking a reasoned successor?
Will alerts detect signing or archival failure, not merely rendering failure?

If any answer is vague, moving the layout will not fix the system. Clear authority plus immutable evidence is the durable design. HTML and PDF templates are implementation choices inside that boundary.

DEV Community