Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,285 @@
|
||||
/**
|
||||
* Compliance-Audit PDF report renderer.
|
||||
*
|
||||
* Renders an AuditEvent slice into a tamper-evident PDF report suitable
|
||||
* for SOC2 / HIPAA / GDPR auditor evidence packs. The first page is a
|
||||
* cover page with tenant + range + filter summary + verifyAuditChain
|
||||
* integrity outcome; following pages list events as a tabular log.
|
||||
*
|
||||
* The renderer is host-agnostic and async — both the operator CLI
|
||||
* (`toolctrl audit export-pdf …`) and the admin web export route use
|
||||
* it via `serializeAuditEventsToPdf` / `serializeAuditEventsToPdfStream`.
|
||||
*
|
||||
* See docs/improvement-plan/10-compliance-polish/compliance-audit-export.md.
|
||||
*/
|
||||
import type { Writable } from "node:stream";
|
||||
|
||||
import React from "react";
|
||||
import { Document, Page, StyleSheet, Text, View, renderToBuffer, renderToStream } from "@react-pdf/renderer";
|
||||
|
||||
import { PDF_STREAM_HARD_ROW_LIMIT, ExportPdfRowLimitExceededError } from "./pdf/index.js";
|
||||
|
||||
export const AUDIT_PDF_CONTENT_TYPE = "application/pdf" as const;
|
||||
export const AUDIT_PDF_HARD_ROW_LIMIT = PDF_STREAM_HARD_ROW_LIMIT;
|
||||
|
||||
export type AuditPdfEvent = {
|
||||
id: string;
|
||||
createdAt: Date | string;
|
||||
tenantId: string | null;
|
||||
actorType: string;
|
||||
actorId: string | null;
|
||||
actorEmail: string | null;
|
||||
actorIp: string | null;
|
||||
actorUserAgent: string | null;
|
||||
action: string;
|
||||
targetType: string | null;
|
||||
targetId: string | null;
|
||||
requestId: string | null;
|
||||
sourceModule: string | null;
|
||||
outcome: string;
|
||||
dataSensitivity: string;
|
||||
regulatoryScope: ReadonlyArray<string>;
|
||||
metadata: unknown;
|
||||
previousHash: string | null;
|
||||
eventHash: string | null;
|
||||
};
|
||||
|
||||
export type AuditPdfIntegrity = {
|
||||
ok: boolean;
|
||||
inspected: number;
|
||||
firstBreakId: string | null;
|
||||
reason: string | null;
|
||||
};
|
||||
|
||||
export type AuditPdfReportInput = {
|
||||
/** Tenant identifier; null = platform-wide. */
|
||||
tenantId: string | null;
|
||||
/** ISO-8601 lower bound used by the export query. */
|
||||
from: string | null;
|
||||
/** ISO-8601 upper bound used by the export query. */
|
||||
to: string | null;
|
||||
/** Free-text filter summary (regulatoryScope/actorType/outcome). */
|
||||
filterSummary: string;
|
||||
/** Pre-computed verifyAuditChain integrity result. */
|
||||
integrity: AuditPdfIntegrity;
|
||||
/** Events in chronological order. */
|
||||
events: ReadonlyArray<AuditPdfEvent>;
|
||||
/** Operator-facing report title (defaults to "Audit-Compliance Report"). */
|
||||
title?: string;
|
||||
/** Human display name of the operator who generated the report. */
|
||||
generatedBy?: string;
|
||||
/** Timestamp of report generation; defaults to new Date(). */
|
||||
generatedAt?: Date;
|
||||
/** Visible report labels; pass localized labels from the caller when needed. */
|
||||
labels?: AuditPdfLabelOverrides;
|
||||
};
|
||||
|
||||
type AuditPdfColumnKey = "createdAt" | "actorType" | "actorId" | "action" | "targetType" | "outcome" | "regulatoryScope" | "eventHash";
|
||||
|
||||
export type AuditPdfLabels = {
|
||||
title: string;
|
||||
tenant: string;
|
||||
platformTenant: string;
|
||||
range: string;
|
||||
openRange: string;
|
||||
filters: string;
|
||||
noFilters: string;
|
||||
generatedBy: string;
|
||||
generatedAt: string;
|
||||
hashChainIntegrity: string;
|
||||
events: (count: number) => string;
|
||||
integrityOk: (inspected: number) => string;
|
||||
integrityBroken: (args: { inspected: number; firstBreakId: string; reason: string }) => string;
|
||||
columns: Record<AuditPdfColumnKey, string>;
|
||||
};
|
||||
|
||||
export type AuditPdfLabelOverrides = Partial<Omit<AuditPdfLabels, "columns">> & {
|
||||
columns?: Partial<AuditPdfLabels["columns"]>;
|
||||
};
|
||||
|
||||
const labelText = (value: string) => value;
|
||||
|
||||
const DEFAULT_AUDIT_PDF_LABELS: AuditPdfLabels = {
|
||||
title: labelText("Audit compliance report"),
|
||||
tenant: "Tenant",
|
||||
platformTenant: "platform",
|
||||
range: "Range",
|
||||
openRange: "open",
|
||||
filters: "Filters",
|
||||
noFilters: "none",
|
||||
generatedBy: "Generated by",
|
||||
generatedAt: "Generated at",
|
||||
hashChainIntegrity: "Hash-chain integrity",
|
||||
events: (count) => `Events (${count})`,
|
||||
integrityOk: (inspected) => `verifyAuditChain OK - inspected ${inspected} events.`,
|
||||
integrityBroken: ({ inspected, firstBreakId, reason }) => `verifyAuditChain BROKEN - inspected ${inspected} events. First-break id=${firstBreakId} reason=${reason}.`,
|
||||
columns: {
|
||||
createdAt: "Time",
|
||||
actorType: "Actor",
|
||||
actorId: "Actor ID",
|
||||
action: "Action",
|
||||
targetType: "Target",
|
||||
outcome: "Outcome",
|
||||
regulatoryScope: "Scope",
|
||||
eventHash: "Hash",
|
||||
},
|
||||
};
|
||||
|
||||
const styles = StyleSheet.create({
|
||||
page: { padding: 32, fontSize: 9, fontFamily: "Helvetica" },
|
||||
title: { fontSize: 18, fontWeight: 700, marginBottom: 12 },
|
||||
subtitle: { fontSize: 12, fontWeight: 700, marginTop: 12, marginBottom: 6 },
|
||||
meta: { marginBottom: 4 },
|
||||
integrityOk: { color: "#047857", fontWeight: 700 },
|
||||
integrityBroken: { color: "#b91c1c", fontWeight: 700 },
|
||||
table: {
|
||||
display: "flex",
|
||||
flexDirection: "column",
|
||||
width: "100%",
|
||||
borderTopWidth: 1,
|
||||
borderLeftWidth: 1,
|
||||
borderColor: "#d1d5db",
|
||||
marginTop: 8,
|
||||
},
|
||||
row: { display: "flex", flexDirection: "row" },
|
||||
headerCell: {
|
||||
flexGrow: 1,
|
||||
flexBasis: 0,
|
||||
padding: 4,
|
||||
fontWeight: 700,
|
||||
backgroundColor: "#f3f4f6",
|
||||
borderRightWidth: 1,
|
||||
borderBottomWidth: 1,
|
||||
borderColor: "#d1d5db",
|
||||
},
|
||||
cell: {
|
||||
flexGrow: 1,
|
||||
flexBasis: 0,
|
||||
padding: 4,
|
||||
borderRightWidth: 1,
|
||||
borderBottomWidth: 1,
|
||||
borderColor: "#d1d5db",
|
||||
},
|
||||
});
|
||||
|
||||
const COLUMNS: ReadonlyArray<{ key: AuditPdfColumnKey; render?: (event: AuditPdfEvent) => string }> = [
|
||||
{ key: "createdAt", render: (e) => (e.createdAt instanceof Date ? e.createdAt.toISOString() : String(e.createdAt)) },
|
||||
{ key: "actorType" },
|
||||
{ key: "actorId", render: (e) => e.actorId ?? "-" },
|
||||
{ key: "action" },
|
||||
{ key: "targetType", render: (e) => `${e.targetType ?? "-"}/${e.targetId ?? "-"}` },
|
||||
{ key: "outcome" },
|
||||
{ key: "regulatoryScope", render: (e) => e.regulatoryScope.join(",") || "-" },
|
||||
{ key: "eventHash", render: (e) => (e.eventHash ? e.eventHash.slice(0, 16) : "-") },
|
||||
];
|
||||
|
||||
function resolveAuditPdfLabels(input?: AuditPdfLabelOverrides): AuditPdfLabels {
|
||||
return {
|
||||
...DEFAULT_AUDIT_PDF_LABELS,
|
||||
...input,
|
||||
columns: {
|
||||
...DEFAULT_AUDIT_PDF_LABELS.columns,
|
||||
...input?.columns,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function buildIntegrityLine(integrity: AuditPdfIntegrity, labels: AuditPdfLabels): string {
|
||||
if (integrity.ok) {
|
||||
return labels.integrityOk(integrity.inspected);
|
||||
}
|
||||
return labels.integrityBroken({
|
||||
inspected: integrity.inspected,
|
||||
firstBreakId: integrity.firstBreakId ?? "?",
|
||||
reason: integrity.reason ?? "unknown",
|
||||
});
|
||||
}
|
||||
|
||||
export function buildAuditPdfDocument(input: AuditPdfReportInput): ReturnType<typeof React.createElement> {
|
||||
const labels = resolveAuditPdfLabels(input.labels);
|
||||
const generatedAt = (input.generatedAt ?? new Date()).toISOString();
|
||||
const integrityStyle = input.integrity.ok ? styles.integrityOk : styles.integrityBroken;
|
||||
const eventRows = input.events.map((event, index) =>
|
||||
React.createElement(
|
||||
View,
|
||||
{ key: `row-${event.id}-${index}`, style: styles.row },
|
||||
...COLUMNS.map((col) => {
|
||||
const raw = col.render ? col.render(event) : (event[col.key] as unknown);
|
||||
const text = raw === null || raw === undefined ? "-" : String(raw);
|
||||
return React.createElement(Text, { key: `${event.id}-${col.key}`, style: styles.cell }, text);
|
||||
})
|
||||
)
|
||||
);
|
||||
|
||||
return React.createElement(
|
||||
Document,
|
||||
{ title: input.title ?? labels.title },
|
||||
React.createElement(
|
||||
Page,
|
||||
{ size: "A4", style: styles.page },
|
||||
React.createElement(Text, { style: styles.title }, input.title ?? labels.title),
|
||||
React.createElement(Text, { style: styles.meta }, `${labels.tenant}: ${input.tenantId ?? `(${labels.platformTenant})`}`),
|
||||
React.createElement(Text, { style: styles.meta }, `${labels.range}: ${input.from ?? `(${labels.openRange})`} ... ${input.to ?? `(${labels.openRange})`}`),
|
||||
React.createElement(Text, { style: styles.meta }, `${labels.filters}: ${input.filterSummary || labels.noFilters}`),
|
||||
input.generatedBy ? React.createElement(Text, { style: styles.meta }, `${labels.generatedBy}: ${input.generatedBy}`) : null,
|
||||
React.createElement(Text, { style: styles.meta }, `${labels.generatedAt}: ${generatedAt}`),
|
||||
React.createElement(Text, { style: styles.subtitle }, labels.hashChainIntegrity),
|
||||
React.createElement(Text, { style: integrityStyle }, buildIntegrityLine(input.integrity, labels)),
|
||||
React.createElement(Text, { style: styles.subtitle }, labels.events(input.events.length)),
|
||||
React.createElement(
|
||||
View,
|
||||
{ style: styles.table },
|
||||
React.createElement(
|
||||
View,
|
||||
{ style: styles.row },
|
||||
...COLUMNS.map((col) =>
|
||||
React.createElement(Text, { key: `head-${col.key}`, style: styles.headerCell }, labels.columns[col.key])
|
||||
)
|
||||
),
|
||||
...eventRows
|
||||
)
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
export async function serializeAuditEventsToPdf(input: AuditPdfReportInput): Promise<Uint8Array> {
|
||||
if (input.events.length > AUDIT_PDF_HARD_ROW_LIMIT) {
|
||||
throw new ExportPdfRowLimitExceededError(input.events.length);
|
||||
}
|
||||
const doc = buildAuditPdfDocument(input);
|
||||
return new Uint8Array(await renderToBuffer(doc));
|
||||
}
|
||||
|
||||
export async function serializeAuditEventsToPdfStream(writeStream: Writable, input: AuditPdfReportInput): Promise<{ rowCount: number }> {
|
||||
if (input.events.length > AUDIT_PDF_HARD_ROW_LIMIT) {
|
||||
throw new ExportPdfRowLimitExceededError(input.events.length);
|
||||
}
|
||||
const doc = buildAuditPdfDocument(input);
|
||||
const readable = await renderToStream(doc);
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
readable.on("error", reject);
|
||||
writeStream.on("error", reject);
|
||||
readable.on("end", () => resolve());
|
||||
readable.pipe(writeStream, { end: false });
|
||||
});
|
||||
return { rowCount: input.events.length };
|
||||
}
|
||||
|
||||
/**
|
||||
* Format the active filters into a compact one-liner suitable for the
|
||||
* cover-page metadata. Shared between CLI and web call-sites so the
|
||||
* report self-describes the operator inputs identically.
|
||||
*/
|
||||
export function summarizeAuditPdfFilters(filters: {
|
||||
regulatoryScope?: ReadonlyArray<string>;
|
||||
actorType?: string | null;
|
||||
outcome?: string | null;
|
||||
}): string {
|
||||
const parts: string[] = [];
|
||||
if (filters.regulatoryScope && filters.regulatoryScope.length > 0) {
|
||||
parts.push(`regulatoryScope=${filters.regulatoryScope.join("|")}`);
|
||||
}
|
||||
if (filters.actorType) parts.push(`actorType=${filters.actorType}`);
|
||||
if (filters.outcome) parts.push(`outcome=${filters.outcome}`);
|
||||
return parts.join(" ");
|
||||
}
|
||||
Reference in new issue
Block a user