First public release

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 14:56:25 -04:00
commit d376475a91
16 changed files with 2360 additions and 0 deletions
@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
@@ -0,0 +1,9 @@
+node_modules/
+dist/
+*.log
+.DS_Store
+.env*
+!.env.example
+.npmrc
+dist/
+dist-cjs/
@@ -0,0 +1,6 @@
+stages: [test]
+
+test:
+  stage: test
+  image: node:22-alpine
+  script: [npm ci, npm run build, npm test]
@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.2.0 - 2026-09-28
+
+First public release under MIT.
+
+- `renderControlDoc()` builds a seven-section NIST 800-53 control document
+  in HTML and markdown from verification checks, with an Evidence section.
+- Checks without evidence are shown as NOT ATTACHED and counted.
+  Unrecognised statuses are counted, never dropped.
+- Output is reproducible: the date is a parameter.
+- All interpolated values are HTML-escaped.
+- `toReport()` and `formatControl()` produce an `@extant2000/evidence-record`
+  report of the same assessment.
@@ -0,0 +1,22 @@
+# Contributing
+
+Issues and merge requests are welcome at
+https://gitlab.com/extant2000/cert-pack.
+
+## Ground rules
+
+- **A test that cannot fail proves nothing.** If you fix a bug, add a test
+  that fails without your fix, and check that it does fail before you submit.
+- Measure, do not assume. Two modules with the same line count can be
+  different programs.
+- Keep dependencies minimal. Every new dependency needs a reason.
+- Explain why in comments, not what.
+
+## Before you open a merge request
+
+Run both of these and make sure they pass:
+
+```
+npm run build
+npm test
+```
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Extant 2000 LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,102 @@
+# CertPack
+
+Generates a NIST 800-53 control document (a System Security Plan section with
+a remediation plan) from automated verification checks, with the evidence for
+each check attached. It is used in Hitt Hosting products.
+
+## What it does and why
+
+An accreditation package that lists results without the scan output behind
+them is a set of claims. **CertPack attaches the evidence to each check and
+labels any check without evidence as a claim.** It does not drop the check or
+leave the cell blank, because a blank cell reads as "nothing to report" and a
+missing check is worse than a weak one.
+
+You pass a control (document number, title, control family, the gap, the fix)
+and a list of checks, each with a status and optional evidence in the
+`@extant2000/evidence-record` format. `renderControlDoc()` returns HTML and
+markdown built from one list of seven sections, so the two never drift apart:
+
+1. Document information
+2. Purpose and scope, including the gap and the deployments in scope
+3. Current implementation status: a table of checks with their evidence, a
+   summary line, and a count of checks with no attached evidence
+4. Remediation plan with a target completion time (30 days by default)
+5. Evidence: the full citation for every check, or a statement that the
+   result is a claim and not a verified finding
+6. References (NIST SP 800-53 Rev. 5, SP 800-53A and the FedRAMP SSP template
+   by default)
+7. Approval and sign-off table
+
+The rules that keep the document from claiming more than it knows:
+
+- A status other than `pass`, `fail` or `warn` is counted as unrecognised and
+  shown in the summary, never folded into another status or dropped.
+- A control with no checks says that an unassessed control is not an
+  implemented control, instead of printing "0 failing".
+- Missing fields print "Not specified", never `undefined` or `null`.
+- The date is a parameter, not read from the clock, so the same input always
+  produces byte-identical output. A document that changes when regenerated is
+  not reproducible evidence.
+
+Every value interpolated into the HTML goes through `escapeHtml()`, including
+titles, table cells and evidence, with no "trusted field" exception. The
+markdown output decodes entities because markdown is not an HTML context; if
+you inject that markdown into a page as HTML, escape it there.
+
+`toReport()` and `formatControl()` give the same assessment as an
+evidence-record report, so a control's status can be rolled up without
+parsing HTML. `pass` passes, `fail` and `warn` fail, and an unrecognised
+status is not assessed.
+
+## Usage
+
+```ts
+import { renderControlDoc, formatControl, type ControlDocInput } from '@extant2000/cert-pack'
+import { evidence } from '@extant2000/evidence-record'
+
+const input: ControlDocInput = {
+  docNumber: 'SSP-AC-01',
+  title: 'Access Control',
+  family: 'AC',
+  familyName: 'Access Control',
+  gap: 'Tenant isolation is not documented',
+  fix: 'Document the row-level security policy',
+  date: '2026-09-28',
+  systemName: 'Example App',
+  checks: [
+    { check: 'Row-level security on every tenant table', status: 'pass',
+      evidence: [evidence.command('psql -c "select relname, relrowsecurity from pg_class ..."', 0, '42 of 42 tables')] },
+    { check: 'Least privilege enforced', status: 'pass' },
+    { check: 'MFA for admins', status: 'skipped' },
+  ],
+}
+
+const { html, markdown, sections } = renderControlDoc(input)
+console.log(formatControl(input))
+```
+
+In the generated document, section 3 ends with "2 passing, 0 failing, 0
+warnings, 1 unrecognised out of 3 checks" and "2 of 3 check(s) carry no
+attached evidence". The two checks without evidence show NOT ATTACHED.
+`formatControl()` prints:
+
+```
+✗ HIGH     MFA for admins   [NOT ASSESSED]
+             Status "skipped" is not recognised. An unrecognised status is not a passing one.
+◦ info     Row-level security on every tenant table   [MET]
+◦ info     Least privilege enforced   [MET]
+```
+
+`controlDocSections()`, `renderDocument()`, `table()`, `stripTags()`,
+`escapeHtml()` and `tally()` are exported for building other documents.
+
+## Install
+
+```
+npm install @extant2000/cert-pack
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,6 @@
+# Security
+
+Please report vulnerabilities privately by email to security@extant2000.com.
+Do not open a public issue for a security problem.
+
+We aim to acknowledge every report within 5 business days.
@@ -0,0 +1,43 @@
+{
+  "name": "@extant2000/cert-pack",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Builds certification evidence packages from scan results.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/extant2000/cert-pack.git"
+  },
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "dependencies": {
+    "@extant2000/evidence-record": "^0.1.2"
+  },
+  "author": "Extant 2000 LLC",
+  "homepage": "https://gitlab.com/extant2000/cert-pack",
+  "bugs": {
+    "url": "https://gitlab.com/extant2000/cert-pack/-/issues"
+  }
+}
@@ -0,0 +1,229 @@
+import { type Evidence, cite, citeVerbose } from '@extant2000/evidence-record'
+import {
+  escapeHtml,
+  renderDocument,
+  table,
+  type DocSection,
+  type RenderedDocument,
+} from './html.js'
+
+/** Outcome of a single automated verification check against a control. */
+export interface VerificationCheck {
+  check: string
+  /** 'pass' | 'fail' | 'warn' — anything else counts as unknown. */
+  status: string
+  /**
+   * What produced this result: the scan output, the file, the row, the
+   * command that was run.
+   *
+   * For an accreditation package this is the difference between a claim and
+   * evidence, and it is exactly what SustainScore's rubric penalises under
+   * "Unverified = absent". A check with no evidence still renders — it is
+   * labelled as unevidenced rather than dropped, because a missing check is
+   * worse than a weak one.
+   */
+  evidence?: Evidence[]
+}
+
+export interface VerificationTally {
+  pass: number
+  fail: number
+  warn: number
+  /** Checks whose status is none of the above. Counted, never ignored. */
+  unknown: number
+  total: number
+}
+
+/**
+ * Tally verification outcomes.
+ *
+ * `unknown` is tracked explicitly rather than folded into `warn` or dropped: a
+ * status the tool does not recognise is not a passing status, and an
+ * accreditation package that quietly loses checks is worse than one that says
+ * it does not know.
+ */
+export function tally(checks: VerificationCheck[]): VerificationTally {
+  const t: VerificationTally = { pass: 0, fail: 0, warn: 0, unknown: 0, total: checks.length }
+  for (const c of checks) {
+    switch (c.status) {
+      case 'pass': t.pass++; break
+      case 'fail': t.fail++; break
+      case 'warn': t.warn++; break
+      default: t.unknown++
+    }
+  }
+  return t
+}
+
+export interface ControlDocInput {
+  /** Document identifier, e.g. "SSP-AC-01". */
+  docNumber: string
+  title: string
+  /** Control family short code, e.g. "AC". */
+  family?: string | null
+  /** Control family long name, e.g. "Access Control". */
+  familyName?: string | null
+  /** The gap this document exists to address. */
+  gap?: string | null
+  /** The remediation. */
+  fix?: string | null
+  checks?: VerificationCheck[]
+  /** ISO date. Injected rather than read from the clock, so output is testable. */
+  date: string
+  classification?: string
+  status?: string
+  version?: string
+  /** Deployment configurations in scope. */
+  deployments?: string[]
+  /** Reference list. Sensible NIST/FedRAMP defaults if omitted. */
+  references?: string[]
+  /** Sign-off roles. */
+  approvers?: string[]
+  /** Product/system name used in prose. */
+  systemName?: string
+  /** Days allowed for remediation, used in the timeline sentence. */
+  remediationDays?: number
+}
+
+const DEFAULT_REFERENCES = [
+  'NIST Special Publication 800-53 Rev. 5 — Security and Privacy Controls for Information Systems',
+  'NIST SP 800-53A — Assessing Security and Privacy Controls',
+  'FedRAMP System Security Plan (SSP) Template',
+]
+
+const DEFAULT_APPROVERS = [
+  'Document Author',
+  'Security Reviewer',
+  'System Owner',
+  'Authorizing Official',
+]
+
+/**
+ * Build the section list for a NIST 800-53 control document (SSP body with an
+ * embedded POA&M-style remediation plan).
+ *
+ * Pure: `date` is a parameter, not `new Date()`. A document generator that
+ * reads the clock cannot be tested for exact output, and an accreditation
+ * artifact that changes when regenerated is not reproducible evidence.
+ */
+export function controlDocSections(input: ControlDocInput): DocSection[] {
+  const family = input.family || 'Unknown'
+  const familyName = input.familyName || 'Unknown'
+  const gap = input.gap || 'Not specified'
+  const fix = input.fix || 'Not specified'
+  const checks = input.checks ?? []
+  const t = tally(checks)
+  const system = input.systemName || 'the system'
+  const days = input.remediationDays ?? 30
+
+  const deployments = input.deployments ?? []
+  const deploymentList = deployments.length
+    ? `<p>This document applies to all ${escapeHtml(system)} deployment configurations including:</p><ul>${
+        deployments.map(d => `<li>${escapeHtml(d)}</li>`).join('')}</ul>`
+    : ''
+
+  const unevidenced = checks.filter(c => (c.evidence?.length ?? 0) === 0).length
+
+  const summary = t.unknown > 0
+    ? `${t.pass} passing, ${t.fail} failing, ${t.warn} warnings, ${t.unknown} unrecognised out of ${t.total} checks.`
+    : `${t.pass} passing, ${t.fail} failing, ${t.warn} warnings out of ${t.total} checks.`
+
+  return [
+    {
+      title: '1. Document Information',
+      content: [
+        `<p><strong>Document Number:</strong> ${escapeHtml(input.docNumber)}</p>`,
+        `<p><strong>Title:</strong> ${escapeHtml(input.title)}</p>`,
+        `<p><strong>NIST 800-53 Control Family:</strong> ${escapeHtml(family)} — ${escapeHtml(familyName)}</p>`,
+        `<p><strong>Classification:</strong> ${escapeHtml(input.classification || 'Unclassified')}</p>`,
+        `<p><strong>Status:</strong> ${escapeHtml(input.status || 'Draft')}</p>`,
+        `<p><strong>Generated:</strong> ${escapeHtml(input.date)}</p>`,
+        `<p><strong>Version:</strong> ${escapeHtml(input.version || '1.0')}</p>`,
+      ].join(''),
+    },
+    {
+      title: '2. Purpose and Scope',
+      content: [
+        `<p>This document addresses a compliance gap identified during the NIST 800-53 control assessment for ${escapeHtml(system)}. `,
+        `The ${escapeHtml(family)} (${escapeHtml(familyName)}) control family requires specific documentation to demonstrate implementation of security controls.</p>`,
+        `<h3>Gap Identified</h3><p>${escapeHtml(gap)}</p>`,
+        deploymentList ? `<h3>Scope</h3>${deploymentList}` : '',
+      ].join(''),
+    },
+    {
+      title: '3. Current Implementation Status',
+      content: [
+        `<p>The following verification checks were evaluated for the ${escapeHtml(family)} control family:</p>`,
+        checks.length
+          ? table(
+              ['Check', 'Status', 'Evidence'],
+              checks.map(c => [
+                c.check || 'Unknown check',
+                (c.status || 'unknown').toUpperCase(),
+                // Unevidenced is stated, not left blank. A blank cell in an
+                // accreditation package reads as "nothing to report"; this
+                // reads as what it is.
+                (c.evidence?.length ?? 0) === 0
+                  ? 'NOT ATTACHED'
+                  : c.evidence!.map(e => cite(e)).join('; '),
+              ]),
+            )
+          : '<p><em>No automated verification checks have been run for this control family. '
+            + 'An unassessed control is not an implemented control.</em></p>',
+        `<p><strong>Summary:</strong> ${escapeHtml(summary)}</p>`,
+        unevidenced > 0
+          ? `<p><strong>${unevidenced} of ${t.total} check(s) carry no attached evidence.</strong> `
+            + 'An asserted result is not a verified one; these are recorded as claims pending evidence.</p>'
+          : '',
+      ].join(''),
+    },
+    {
+      title: '4. Remediation Plan',
+      content: [
+        `<h3>Required Action</h3><p>${escapeHtml(fix)}</p>`,
+        '<h3>Implementation Steps</h3><ol>',
+        '<li>Review the current implementation status above and identify all failing controls</li>',
+        '<li>Implement the required action described above</li>',
+        '<li>Verify the implementation by re-running the verification checks</li>',
+        '<li>Update this document with the verification results</li>',
+        '<li>Submit for security review and approval</li>',
+        '</ol>',
+        `<h3>Timeline</h3><p>This remediation should be completed prior to authorization submission. `,
+        `Target completion: within ${escapeHtml(days)} days of document generation.</p>`,
+      ].join(''),
+    },
+    {
+      title: '5. Evidence',
+      content: checks.length
+        ? checks.map(c => {
+            const head = `<h3>${escapeHtml(c.check || 'Unknown check')} — ${escapeHtml((c.status || 'unknown').toUpperCase())}</h3>`
+            if ((c.evidence?.length ?? 0) === 0) {
+              return head + '<p><em>No evidence attached. This result is a claim, not a verified finding.</em></p>'
+            }
+            return head + `<ul>${c.evidence!.map(e =>
+              `<li>${citeVerbose(e).map(l => escapeHtml(l.trim())).join('<br>')}</li>`).join('')}</ul>`
+          }).join('')
+        : '<p><em>No checks were run, so no evidence exists to attach.</em></p>',
+    },
+    {
+      title: '6. References',
+      content: `<ul>${(input.references ?? DEFAULT_REFERENCES).map(r => `<li>${escapeHtml(r)}</li>`).join('')}</ul>`,
+    },
+    {
+      title: '7. Approval and Sign-Off',
+      content: [
+        table(
+          ['Role', 'Name', 'Signature', 'Date'],
+          (input.approvers ?? DEFAULT_APPROVERS).map(role => [role, '', '', '']),
+        ),
+        `<p><em>This document was auto-generated on ${escapeHtml(input.date)}. `,
+        'It should be reviewed, completed, and approved by qualified security personnel before submission.</em></p>',
+      ].join(''),
+    },
+  ]
+}
+
+/** Render a control document to HTML + markdown. */
+export function renderControlDoc(input: ControlDocInput): RenderedDocument {
+  return renderDocument(controlDocSections(input))
+}
@@ -0,0 +1,88 @@
+/**
+ * HTML/markdown primitives for compliance document rendering.
+ *
+ * These are separated out because escaping is the part that must be right
+ * everywhere and is easiest to forget in one template out of six. Any renderer
+ * that interpolates caller-controlled values into markup uses `escapeHtml`;
+ * there is no "this field is trusted" exception.
+ */
+
+/**
+ * Escape HTML entities in caller-controllable strings interpolated into
+ * document templates. Prevents stored-XSS when data reaches control metadata,
+ * finding descriptions, or evidence references.
+ */
+export function escapeHtml(input: unknown): string {
+  const str = input == null ? '' : String(input)
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+/**
+ * Strip tags and collapse whitespace to produce a markdown body.
+ *
+ * NOTE the entity decoding at the end: it deliberately UNDOES `escapeHtml`,
+ * because markdown is not an HTML context and a reader should see `<` rather
+ * than `&lt;`. That is only safe while the consumer re-escapes when it renders
+ * markdown to HTML. If you add a consumer that injects this string into the
+ * DOM directly, escape it there — the safety lives at the render boundary, not
+ * in this function.
+ */
+export function stripTags(html: string): string {
+  return html
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/(p|li|tr|div|h[1-6])>/gi, '\n')
+    .replace(/<li>/gi, '- ')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\n{3,}/g, '\n\n')
+}
+
+export interface DocSection {
+  title: string
+  /** HTML fragment. Interpolated values MUST already be escaped. */
+  content: string
+}
+
+export interface RenderedDocument {
+  html: string
+  markdown: string
+  sections: DocSection[]
+}
+
+/**
+ * Render sections into both an HTML document and a markdown equivalent.
+ *
+ * Both are returned so a consumer can pick: a rich renderer takes `html`, a
+ * plain one takes `markdown`. Producing them from one section list is what
+ * keeps the two from drifting into different documents.
+ */
+export function renderDocument(sections: DocSection[]): RenderedDocument {
+  const html = sections
+    .map(s => `<section><h2>${escapeHtml(s.title)}</h2>${s.content}</section>`)
+    .join('\n')
+
+  const markdown = sections
+    .map(s => `## ${s.title}\n\n${stripTags(s.content).trim()}\n`)
+    .join('\n')
+
+  return { html, markdown, sections }
+}
+
+/** Build an escaped HTML table. Cells are escaped; headers are escaped. */
+export function table(headers: string[], rows: unknown[][]): string {
+  const head = headers.map(h => `<th>${escapeHtml(h)}</th>`).join('')
+  const body = rows
+    .map(r => `<tr>${r.map(c => `<td>${escapeHtml(c)}</td>`).join('')}</tr>`)
+    .join('')
+  return `<table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`
+}
@@ -0,0 +1,3 @@
+export * from './html.js'
+export * from './control-doc.js'
+export { toReport, formatControl } from './report.js'
@@ -0,0 +1,53 @@
+import {
+  type CapabilityReport,
+  type Determination,
+  type FormatOptions,
+  formatReport as renderReport,
+} from '@extant2000/evidence-record'
+import type { ControlDocInput, VerificationCheck } from './control-doc.js'
+
+function determinationFor(status: string): Determination {
+  switch (status) {
+    case 'pass': return 'pass'
+    case 'fail': return 'fail'
+    case 'warn': return 'fail'
+    // An unrecognised status is not a passing status. Folding it into `warn`
+    // or dropping it is how an accreditation package quietly loses a check.
+    default: return 'not-assessed'
+  }
+}
+
+/**
+ * Report the control assessment behind the document.
+ *
+ * The document is the deliverable; this is the machine-readable view of the
+ * same facts, so a control's status can be rolled up across a portfolio
+ * without parsing HTML.
+ */
+export function toReport(input: ControlDocInput): CapabilityReport {
+  const checks: VerificationCheck[] = input.checks ?? []
+
+  return {
+    capability: 'CertPack',
+    scope: `${input.docNumber} — ${input.family ?? 'Unknown'} control family`,
+    examined: checks.length,
+    findings: checks.map((c, i) => ({
+      id: `check-${i}`,
+      summary: c.check || 'Unknown check',
+      determination: determinationFor(c.status),
+      severity: c.status === 'fail' ? 'critical' : c.status === 'warn' ? 'high' : c.status === 'pass' ? 'info' : 'high',
+      detail: determinationFor(c.status) === 'not-assessed' && c.status !== 'pass' && c.status !== 'fail' && c.status !== 'warn'
+        ? `Status "${c.status}" is not recognised. An unrecognised status is not a passing one.`
+        : undefined,
+      evidence: c.evidence ?? [],
+    })),
+    notes: checks.length === 0
+      ? ['No automated verification checks have been run for this control family. An unassessed control is not an implemented control.']
+      : [],
+  }
+}
+
+/** Render the control assessment for a terminal or CI log. */
+export function formatControl(input: ControlDocInput, opts: FormatOptions = {}): string {
+  return renderReport(toReport(input), opts)
+}
@@ -0,0 +1,240 @@
+import { describe, expect, it } from 'vitest'
+import { evidence, overall, validateReport } from '@extant2000/evidence-record'
+import {
+  controlDocSections,
+  toReport,
+  formatControl,
+  escapeHtml,
+  renderControlDoc,
+  renderDocument,
+  stripTags,
+  table,
+  tally,
+} from '../src/index.js'
+
+const base = { docNumber: 'SSP-AC-01', title: 'Access Control', date: '2026-07-28' }
+
+describe('escapeHtml', () => {
+  it('escapes every dangerous character', () => {
+    expect(escapeHtml(`<script>"x"&'y'`))
+      .toBe('&lt;script&gt;&quot;x&quot;&amp;&#39;y&#39;')
+  })
+
+  it('escapes ampersands first so entities are not double-broken', () => {
+    expect(escapeHtml('&lt;')).toBe('&amp;lt;')
+  })
+
+  it('renders null and undefined as empty, not "null"', () => {
+    expect(escapeHtml(null)).toBe('')
+    expect(escapeHtml(undefined)).toBe('')
+  })
+
+  it('coerces non-strings', () => {
+    expect(escapeHtml(42)).toBe('42')
+  })
+})
+
+describe('table', () => {
+  it('escapes both headers and cells', () => {
+    const html = table(['<h>'], [['<script>alert(1)</script>']])
+    expect(html).toContain('&lt;h&gt;')
+    expect(html).toContain('&lt;script&gt;')
+    expect(html).not.toContain('<script>')
+  })
+})
+
+describe('renderDocument', () => {
+  it('escapes section titles', () => {
+    const { html } = renderDocument([{ title: '<img onerror=x>', content: '<p>ok</p>' }])
+    expect(html).toContain('&lt;img onerror=x&gt;')
+    expect(html).not.toContain('<img')
+  })
+
+  it('produces html and markdown from one section list', () => {
+    const r = renderDocument([{ title: 'One', content: '<p>Body text</p>' }])
+    expect(r.html).toContain('<section><h2>One</h2>')
+    expect(r.markdown).toContain('## One')
+    expect(r.markdown).toContain('Body text')
+    expect(r.sections).toHaveLength(1)
+  })
+})
+
+describe('stripTags', () => {
+  it('decodes entities — markdown is not an HTML context', () => {
+    // Documented and deliberate: it undoes escapeHtml so a reader sees `<`.
+    // Safe only because the consumer re-escapes at the render boundary.
+    expect(stripTags('<p>&lt;tag&gt;</p>').trim()).toBe('<tag>')
+  })
+
+  it('turns list items into markdown bullets', () => {
+    expect(stripTags('<ul><li>a</li><li>b</li></ul>')).toContain('- a')
+  })
+
+  it('collapses runs of blank lines', () => {
+    expect(stripTags('<p>a</p><p></p><p></p><p></p><p>b</p>')).not.toMatch(/\n{3,}/)
+  })
+})
+
+describe('tally', () => {
+  it('counts each status', () => {
+    expect(tally([
+      { check: 'a', status: 'pass' },
+      { check: 'b', status: 'fail' },
+      { check: 'c', status: 'warn' },
+    ])).toEqual({ pass: 1, fail: 1, warn: 1, unknown: 0, total: 3 })
+  })
+
+  it('counts an unrecognised status as unknown rather than dropping it', () => {
+    // A status the tool does not recognise is not a passing status, and an
+    // accreditation package must not quietly lose checks.
+    const t = tally([{ check: 'a', status: 'skipped' }, { check: 'b', status: 'pass' }])
+    expect(t.unknown).toBe(1)
+    expect(t.total).toBe(2)
+    expect(t.pass).toBe(1)
+  })
+
+  it('handles an empty set', () => {
+    expect(tally([])).toEqual({ pass: 0, fail: 0, warn: 0, unknown: 0, total: 0 })
+  })
+})
+
+describe('controlDocSections', () => {
+  it('emits the seven standard sections in order', () => {
+    const titles = controlDocSections(base).map(s => s.title)
+    expect(titles).toEqual([
+      '1. Document Information',
+      '2. Purpose and Scope',
+      '3. Current Implementation Status',
+      '4. Remediation Plan',
+      '5. Evidence',
+      '6. References',
+      '7. Approval and Sign-Off',
+    ])
+  })
+
+  it('escapes hostile input in every field it interpolates', () => {
+    const { html } = renderControlDoc({
+      ...base,
+      title: '<script>alert(1)</script>',
+      family: '<img src=x onerror=1>',
+      gap: '"><script>bad()</script>',
+      fix: `'; DROP TABLE--`,
+      checks: [{ check: '<b>evil</b>', status: '<i>pass</i>' }],
+    })
+    expect(html).not.toContain('<script>')
+    expect(html).not.toContain('<img src=x')
+    expect(html).not.toContain('<b>evil</b>')
+    expect(html).toContain('&lt;script&gt;')
+  })
+
+  it('does NOT report an unassessed control as clean', () => {
+    // With no checks, "0 failing" would read as a pass. Say so explicitly.
+    const s = controlDocSections({ ...base, checks: [] })
+    const status = s.find(x => x.title.startsWith('3.'))!
+    expect(status.content).toContain('An unassessed control is not an implemented control')
+  })
+
+  it('surfaces unrecognised statuses in the summary line', () => {
+    const s = controlDocSections({
+      ...base,
+      checks: [{ check: 'a', status: 'weird' }, { check: 'b', status: 'pass' }],
+    })
+    expect(s.find(x => x.title.startsWith('3.'))!.content).toContain('1 unrecognised')
+  })
+
+  it('omits the unrecognised clause when there are none', () => {
+    const s = controlDocSections({ ...base, checks: [{ check: 'a', status: 'pass' }] })
+    expect(s.find(x => x.title.startsWith('3.'))!.content).not.toContain('unrecognised')
+  })
+
+  it('is reproducible — same input, byte-identical output', () => {
+    // The date is a parameter, not new Date(). An accreditation artifact that
+    // changes when regenerated is not reproducible evidence.
+    const a = renderControlDoc({ ...base, gap: 'g', fix: 'f' })
+    const b = renderControlDoc({ ...base, gap: 'g', fix: 'f' })
+    expect(a.html).toBe(b.html)
+    expect(a.markdown).toBe(b.markdown)
+  })
+
+  it('falls back to "Not specified" rather than printing undefined', () => {
+    const { markdown } = renderControlDoc(base)
+    expect(markdown).toContain('Not specified')
+    expect(markdown).not.toContain('undefined')
+    expect(markdown).not.toContain('null')
+  })
+
+  it('accepts custom references, approvers, deployments and timeline', () => {
+    const { html } = renderControlDoc({
+      ...base,
+      references: ['ISO 27001'],
+      approvers: ['CISO'],
+      deployments: ['Air-gapped'],
+      remediationDays: 14,
+      systemName: 'Extant 2000',
+    })
+    expect(html).toContain('ISO 27001')
+    expect(html).toContain('CISO')
+    expect(html).toContain('Air-gapped')
+    expect(html).toContain('within 14 days')
+    expect(html).toContain('Extant 2000')
+  })
+
+  it('omits the scope list entirely when no deployments are given', () => {
+    expect(renderControlDoc(base).html).not.toContain('<h3>Scope</h3>')
+  })
+})
+
+describe('evidence attached, not asserted', () => {
+  const base = { docNumber: 'SSP-AC-01', title: 'Access Control', family: 'AC', date: '2026-08-01' }
+
+  it('renders the evidence behind each check, not just its status', () => {
+    // The gap this closes: CertPack rendered a document asserting results
+    // without attaching the scan output that produced them.
+    const doc = renderControlDoc({
+      ...base,
+      checks: [{
+        check: 'RLS enabled on every tenant table',
+        status: 'pass',
+        evidence: [evidence.command('psql -c "select relrowsecurity..."', 0, '42 of 42 tables')],
+      }],
+    })
+    expect(doc.html).toContain('42 of 42 tables')
+    expect(doc.html).toContain('5. Evidence')
+  })
+
+  it('labels an unevidenced check as a claim rather than leaving it blank', () => {
+    // A blank cell in an accreditation package reads as "nothing to report".
+    const doc = renderControlDoc({
+      ...base,
+      checks: [{ check: 'Least privilege enforced', status: 'pass' }],
+    })
+    expect(doc.html).toContain('NOT ATTACHED')
+    expect(doc.html).toContain('carry no attached evidence')
+    expect(doc.html).toContain('This result is a claim, not a verified finding')
+  })
+
+  it('says so when there are no checks at all', () => {
+    const doc = renderControlDoc(base)
+    expect(doc.html).toContain('An unassessed control is not an implemented control')
+    expect(doc.html).toContain('no evidence exists to attach')
+  })
+
+  it('an unrecognised status is not-assessed, never a pass', () => {
+    const r = toReport({ ...base, checks: [{ check: 'x', status: 'skipped' }] })
+    expect(r.findings[0]!.determination).toBe('not-assessed')
+    expect(overall(r)).toBe('not-assessed')
+  })
+
+  it('a zero-check control reports NOT ASSESSED', () => {
+    expect(overall(toReport(base))).toBe('not-assessed')
+    expect(formatControl(base)).toContain('NOT ASSESSED')
+  })
+
+  it('every conclusion carries a citation', () => {
+    const r = toReport({
+      ...base,
+      checks: [{ check: 'RLS enabled', status: 'pass', evidence: [evidence.command('psql', 0)] }],
+    })
+    expect(validateReport(r)).toEqual([])
+  })
+})
@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "ES2022", "moduleResolution": "bundler",
+    "declaration": true, "outDir": "dist", "rootDir": "src",
+    "strict": true, "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}