fix(audit-wave-9): PDF correctness + brand asset hardening (pdf-auditor)

Address the pdf-auditor findings that survived the 2026-05-12 PDF stack
overhaul (pdfme → react-pdf). Items C-2/C-3 (tiptap-to-pdfme bugs) were
resolved when that 571-LOC bridge was deleted; remaining items:

- **M-7 wrong-port brand fallback** — replace `'Port Nimara'` defaults
  in PDF-rendering services. `reports.service` and `expense-export`
  throw when the port row is missing (the job is FK-keyed on a real
  port, so absence = broken state, must not stamp a competitor brand).
  `record-export` uses `'(port)'` as the visible placeholder.

- **M-2 silent field drift in fill-eoi-form** — promote the
  always-silent catch in `setText` / `setCheckbox` to log a structured
  warning per missing field (mirroring the existing `setBerthRange`
  pattern). A re-cut template with drifted AcroForm field names now
  surfaces in ops logs instead of shipping with empty values.

- **M-3 form not flattened** — `fillEoiFormFields` now flattens the
  AcroForm before save. Documenso pathway flattens server-side; this
  brings the in-app pathway to parity, so the signer can't edit
  pre-filled yacht dimensions / address / berth number after the fact.

- **M-1 PDF metadata** — set Title / Author / Subject / Lang / Producer
  / Creator on the generated EOI PDF for downstream readers and a11y
  tooling.

- **M-4 noisy berth-range warnings** — downgrade per-mooring warn to
  debug; emit a single summary warn per call when any passthrough
  occurred. Multi-berth EOIs with archived/legacy moorings no longer
  spam the log on every render.

- **M-6 source PDF sha pinning** — pin
  `assets/eoi-template.pdf` sha256 via `EXPECTED_EOI_SHA256` (exported
  for tests); `loadEoiTemplatePdf` warns once per process when the
  bytes drift without an explicit hash bump. Documented the
  intentional-update workflow in `assets/README.md`.

Tests updated in `tests/unit/pdf/fill-eoi-form.test.ts` to reflect
flatten + metadata (form fields are gone after flatten; pdf-lib has no
getLanguage so we assert the other setters round-trip).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/lib/pdf/fill-eoi-form.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
@@ -6,6 +7,17 @@ import { PDFDocument } from 'pdf-lib';
 import type { EoiContext } from '@/lib/services/eoi-context';
 import { logger } from '@/lib/logger';
 
+/**
+ * Pinned sha256 of `assets/eoi-template.pdf`. Bump this AND the README
+ * checksum in lockstep when the template is intentionally re-cut. A
+ * mismatch only logs a warning (we don't want a malformed swap to take
+ * the EOI flow offline at boot), but ops monitoring will surface it.
+ */
+export const EXPECTED_EOI_SHA256 =
+  'ba495fd88d99ebe4b7f61acbe397fb2f1cd116e1e1f1b217de93106915c7c44b';
+
+let shaCheckPerformed = false;
+
 /**
  * Source PDF for the in-app EOI pathway. Must contain AcroForm fields whose
  * names match the Documenso template's `formValues` keys exactly:
@@ -25,13 +37,32 @@ function eoiTemplatePath(): string {
 
 export async function loadEoiTemplatePdf(): Promise<Uint8Array> {
   const filePath = eoiTemplatePath();
+  let bytes: Buffer;
   try {
-    return await fs.readFile(filePath);
+    bytes = await fs.readFile(filePath);
   } catch (err) {
     throw new Error(
       `EOI source PDF not found at ${filePath}. Drop the same PDF used by the Documenso template (with AcroForm fields: Name, Email, Address, Yacht Name, Length, Width, Draft, Berth Number, Lease_10, Purchase) at this path, or override via EOI_TEMPLATE_PDF_PATH. Original error: ${(err as Error).message}`,
     );
   }
+
+  // SHA-pin check (M-6): warn once per process when the template's bytes
+  // don't match the committed hash. Skipped entirely when the override
+  // env var is in play (fixture / dev workflows are expected to use
+  // arbitrary PDFs). Only checks the default path so test setups stay
+  // unconstrained.
+  if (!shaCheckPerformed && !process.env.EOI_TEMPLATE_PDF_PATH) {
+    shaCheckPerformed = true;
+    const actual = createHash('sha256').update(bytes).digest('hex');
+    if (actual !== EXPECTED_EOI_SHA256) {
+      logger.warn(
+        { expected: EXPECTED_EOI_SHA256, actual },
+        'EOI source PDF sha256 mismatch — template was modified without an EXPECTED_EOI_SHA256 bump. Update assets/README.md + EXPECTED_EOI_SHA256 in lockstep if this was intentional.',
+      );
+    }
+  }
+
+  return bytes;
 }
 
 function formatAddress(address: EoiContext['client']['address']): string {
@@ -43,9 +74,18 @@ function setText(form: ReturnType<PDFDocument['getForm']>, name: string, value:
   try {
     form.getTextField(name).setText(value);
   } catch {
-    // Field absent or wrong type - skip silently so a slightly different PDF
-    // template still produces output. Missing field issues surface in QA, not
-    // at runtime as a 500.
+    // Field absent or wrong type - skip so a slightly different PDF
+    // template still produces output, but surface a warning so a re-cut
+    // template with drifted field names is observable in ops logs
+    // instead of shipping silently with empty values. Only warn when
+    // there's a real value to render; an empty value would be a no-op
+    // even if the field existed.
+    if (value && value.trim().length > 0) {
+      logger.warn(
+        { field: name },
+        `EOI in-app PDF template is missing AcroForm field "${name}" — value was dropped. Update the source template.`,
+      );
+    }
   }
 }
 
@@ -81,7 +121,10 @@ function setCheckbox(
     if (checked) cb.check();
     else cb.uncheck();
   } catch {
-    // See comment in setText.
+    logger.warn(
+      { field: name, checked },
+      `EOI in-app PDF template is missing checkbox AcroForm field "${name}" — checkbox state was dropped. Update the source template.`,
+    );
   }
 }
 
@@ -90,8 +133,11 @@ function setCheckbox(
  * EoiContext. Field names mirror the Documenso template `formValues` keys so
  * a single source PDF can serve both pathways.
  *
- * The form is left interactive (not flattened) so a recipient can still tweak
- * fields if needed before signing.
+ * The form is **flattened** after filling so the recipient can't edit
+ * pre-filled values (yacht dimensions, address, berth number) after the
+ * fact. Documenso pathway flattens server-side; this brings the in-app
+ * pathway to parity. Set metadata so the artifact carries Title/Author/
+ * Lang for downstream readers and a11y tooling.
  */
 export async function fillEoiFormFields(
   pdfBytes: Uint8Array,
@@ -121,6 +167,17 @@ export async function fillEoiFormFields(
   setCheckbox(form, 'Purchase', true);
   setCheckbox(form, 'Lease_10', false);
 
+  // PDF metadata so the artifact carries Title/Author/Lang downstream.
+  doc.setTitle(`EOI – ${context.client.fullName}`);
+  doc.setAuthor(context.port.name);
+  doc.setSubject('Expression of Interest');
+  doc.setLanguage('en-GB');
+  doc.setProducer('Port CRM');
+  doc.setCreator('Port CRM');
+
+  // Flatten so the signer can't edit pre-filled values after the fact.
+  form.flatten();
+
   return doc.save();
 }
 

src/lib/services/expense-export.tsx

@@ -134,10 +134,13 @@ export async function exportParentCompany(
     db.query.ports.findFirst({ where: eq(ports.id, portId) }),
     resolvePortLogo(portId),
   ]);
+  if (!port) {
+    throw new Error(`Cannot render expense export: port ${portId} not found.`);
+  }
 
   return renderPdf(
     <ParentCompanyExpensePdf
-      portName={port?.name ?? 'Port Nimara'}
+      portName={port.name}
       logoBuffer={logo.buffer}
       rows={convertedRows}
       subtotal={subtotal}

src/lib/services/record-export.tsx

@@ -107,7 +107,7 @@ export async function exportClientPdf(clientId: string, portId: string): Promise
 
   return renderPdf(
     <ClientSummaryPdf
-      portName={port?.name ?? 'Port Nimara'}
+      portName={port?.name ?? '(port)'}
       logoBuffer={logo.buffer}
       client={{
         fullName: client.fullName,
@@ -218,7 +218,7 @@ export async function exportBerthPdf(berthId: string, portId: string): Promise<U
 
   return renderPdf(
     <BerthSpecPdf
-      portName={port?.name ?? 'Port Nimara'}
+      portName={port?.name ?? '(port)'}
       logoBuffer={logo.buffer}
       berth={{
         mooringNumber: berth.mooringNumber,
@@ -315,7 +315,7 @@ export async function exportInterestPdf(interestId: string, portId: string): Pro
 
   return renderPdf(
     <InterestSummaryPdf
-      portName={port?.name ?? 'Port Nimara'}
+      portName={port?.name ?? '(port)'}
       logoBuffer={logo.buffer}
       interest={{
         id: interest.id,

src/lib/services/reports.service.tsx

@@ -230,8 +230,16 @@ export async function generateReport(reportJobId: string): Promise<void> {
     const port = await db.query.ports.findFirst({
       where: eq(ports.id, portId),
     });
-    const portName = port?.name ?? 'Port Nimara';
-    const portSlug = port?.slug ?? 'port';
+    // The job is keyed on a real port id - port should always resolve here.
+    // If the row is missing, the deployment is in a broken state and we
+    // must not stamp a competitor port's brand on the artifact. Fail loudly.
+    if (!port) {
+      throw new Error(
+        `Cannot render report PDF: port ${portId} not found. Check report job FK integrity.`,
+      );
+    }
+    const portName = port.name;
+    const portSlug = port.slug;
     const logo = await resolvePortLogo(portId);
 
     // 6. Render PDF via react-pdf brand kit

src/lib/templates/berth-range.ts

@@ -61,11 +61,22 @@ export function formatBerthRange(mooringNumbers: readonly string[]): string {
     const p = tryParse(m);
     if (p) parsed.push(p);
     else {
-      logger.warn({ mooring: m }, 'formatBerthRange: non-canonical mooring; passing through');
+      // Per-mooring is debug to keep logs quiet when archived rows
+      // (with " (archived)" / " (deleted)" suffixes) flow through a
+      // bundle; the single summary `warn` below makes the situation
+      // observable without spamming.
+      logger.debug({ mooring: m }, 'formatBerthRange: non-canonical mooring; passing through');
       passthrough.push(m);
     }
   }
 
+  if (passthrough.length > 0) {
+    logger.warn(
+      { count: passthrough.length, samples: passthrough.slice(0, 3) },
+      'formatBerthRange: non-canonical moorings passed through (verbatim, not range-compressed)',
+    );
+  }
+
   // Sort canonical-form moorings by (prefix, number).
   parsed.sort((a, b) => {
     if (a.prefix !== b.prefix) return a.prefix < b.prefix ? -1 : 1;