Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/db/src/audit-chain-checkpoint.server.ts
T

370 lines
13 KiB
TypeScript

import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
import { getDbClient } from "./client.server.js";
import {
canonicalizeAuditPayload,
requireAuditChainSecret,
resolveAuditChainSecret,
verifyAuditChain,
type AuditChainEvent,
} from "./audit-hash.js";
const CHECKPOINT_MAC_PREFIX = "cp1:";
const CHAIN_HEAD_MAC_PREFIX = "ah1:";
export type AuditChainHeadRecord = {
chainKey: string;
tenantId: string | null;
eventId: string;
eventHash: string;
eventCreatedAt: Date;
headMac: string;
};
export type AuditChainCheckpointRecord = {
id: string;
createdAt: Date;
chainKey: string;
tenantId: string | null;
deletedThroughAt: Date;
lastDeletedEventId: string;
lastDeletedEventHash: string | null;
deletedCount: number;
previousCheckpointMac: string | null;
checkpointMac: string;
};
type AuditChainCheckpointCreateData = AuditChainCheckpointRecord;
export type AuditVerificationContext = {
initialPreviousHashes: ReadonlyMap<string, string | null>;
invalidCheckpointChains: ReadonlySet<string>;
};
export type AuditVerificationRow = {
id: string;
createdAt: Date | string;
tenantId: string | null;
previousHash: string | null;
eventHash: string | null;
};
type AuditCheckpointReader = {
auditChainCheckpoint: {
findMany(args: Record<string, unknown>): Promise<AuditChainCheckpointRecord[]>;
};
auditChainCheckpointHead?: {
findMany(args: {
where: { chainKey: { in: string[] } };
select: { chainKey: true; checkpointId: true };
}): Promise<Array<{ chainKey: string; checkpointId: string }>>;
};
};
type AuditRetentionTx = AuditCheckpointReader & {
$queryRaw<T = unknown>(query: TemplateStringsArray, ...values: unknown[]): Promise<T>;
auditEvent: {
findMany(args: Record<string, unknown>): Promise<Array<Omit<AuditChainEvent, "createdAt"> & { createdAt: Date }>>;
findFirst(args: Record<string, unknown>): Promise<{ id: string; previousHash: string | null; eventHash: string | null } | null>;
deleteMany(args: { where: { id: { in: string[] } } }): Promise<{ count: number }>;
};
auditChainCheckpoint: AuditCheckpointReader["auditChainCheckpoint"] & {
findFirst(args: Record<string, unknown>): Promise<AuditChainCheckpointRecord | null>;
findUnique(args: { where: { id: string } }): Promise<AuditChainCheckpointRecord | null>;
create(args: { data: AuditChainCheckpointCreateData }): Promise<AuditChainCheckpointRecord>;
};
auditChainCheckpointHead: {
findUnique(args: {
where: { chainKey: string };
select: { checkpointId: true };
}): Promise<{ checkpointId: string } | null>;
upsert(args: {
where: { chainKey: string };
create: { chainKey: string; tenantId: string | null; checkpointId: string; checkpointMac: string; updatedAt: Date };
update: { tenantId: string | null; checkpointId: string; checkpointMac: string; updatedAt: Date };
}): Promise<unknown>;
};
};
type AuditRetentionClient = {
$transaction<T>(runner: (tx: AuditRetentionTx) => Promise<T>): Promise<T>;
};
export class AuditChainCheckpointError extends Error {
override readonly name = "AuditChainCheckpointError";
}
export function auditChainKey(tenantId: string | null): string {
return tenantId === null ? "platform" : `tenant:${tenantId}`;
}
export function computeAuditCheckpointMac(
checkpoint: Omit<AuditChainCheckpointRecord, "checkpointMac">,
secret?: string | null,
): string {
const key = requireAuditChainSecret(secret);
const canonical = canonicalizeAuditPayload({
id: checkpoint.id,
createdAt: checkpoint.createdAt.toISOString(),
chainKey: checkpoint.chainKey,
tenantId: checkpoint.tenantId,
deletedThroughAt: checkpoint.deletedThroughAt.toISOString(),
lastDeletedEventId: checkpoint.lastDeletedEventId,
lastDeletedEventHash: checkpoint.lastDeletedEventHash,
deletedCount: checkpoint.deletedCount,
previousCheckpointMac: checkpoint.previousCheckpointMac,
});
return `${CHECKPOINT_MAC_PREFIX}${createHmac("sha256", key).update(canonical, "utf8").digest("hex")}`;
}
export function verifyAuditCheckpoint(checkpoint: AuditChainCheckpointRecord, secret?: string | null): boolean {
const expected = computeAuditCheckpointMac(checkpoint, secret);
const expectedBytes = Buffer.from(expected, "utf8");
const actualBytes = Buffer.from(checkpoint.checkpointMac, "utf8");
return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
}
export function computeAuditChainHeadMac(
head: Omit<AuditChainHeadRecord, "headMac">,
secret?: string | null,
): string {
const canonical = canonicalizeAuditPayload({
chainKey: head.chainKey,
tenantId: head.tenantId,
eventId: head.eventId,
eventHash: head.eventHash,
eventCreatedAt: head.eventCreatedAt.toISOString(),
});
const key = resolveAuditChainSecret(secret);
const digest = key
? createHmac("sha256", key).update(canonical, "utf8").digest("hex")
: createHash("sha256").update(canonical, "utf8").digest("hex");
return `${CHAIN_HEAD_MAC_PREFIX}${digest}`;
}
export function verifyAuditChainHead(head: AuditChainHeadRecord, secret?: string | null): boolean {
const expected = computeAuditChainHeadMac(head, secret);
const expectedBytes = Buffer.from(expected, "utf8");
const actualBytes = Buffer.from(head.headMac, "utf8");
return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
}
export async function acquireAuditChainLock(
client: Pick<AuditRetentionTx, "$queryRaw">,
tenantId: string | null,
): Promise<void> {
const key = auditChainKey(tenantId);
// PostgreSQL exposes pg_advisory_xact_lock as `void`. Prisma's driver
// adapter cannot decode that native type (P2010/UnsupportedNativeDataType),
// so return the same lock result through PostgreSQL's stable text codec.
await client.$queryRaw`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))::text AS "lock"`;
}
export async function loadAuditVerificationContext(
client: AuditCheckpointReader,
rows: ReadonlyArray<AuditVerificationRow>,
options: { allowPartialPrefix?: boolean; secret?: string | null } = {},
): Promise<AuditVerificationContext> {
const firstRows = new Map<string, AuditVerificationRow>();
for (const row of [...rows].sort(compareAuditRows)) {
const key = auditChainKey(row.tenantId);
if (!firstRows.has(key) && row.eventHash !== null) firstRows.set(key, row);
}
const keys = [...firstRows.keys()];
let checkpoints: AuditChainCheckpointRecord[] = [];
if (keys.length > 0 && client.auditChainCheckpointHead) {
const heads = await client.auditChainCheckpointHead.findMany({
where: { chainKey: { in: keys } },
select: { chainKey: true, checkpointId: true },
});
if (heads.length > 0) {
checkpoints = await client.auditChainCheckpoint.findMany({
where: { id: { in: heads.map((head) => head.checkpointId) } },
});
}
} else if (keys.length > 0) {
// Compatibility seam for older test doubles. Production clients expose
// AuditChainCheckpointHead, keeping lookup bounded to two queries.
checkpoints = await client.auditChainCheckpoint.findMany({
where: { chainKey: { in: keys } },
orderBy: [{ chainKey: "asc" }, { createdAt: "desc" }, { id: "desc" }],
distinct: ["chainKey"],
});
}
const checkpointByChain = new Map(checkpoints.map((checkpoint) => [checkpoint.chainKey, checkpoint]));
const initialPreviousHashes = new Map<string, string | null>();
const invalidCheckpointChains = new Set<string>();
for (const [key, first] of firstRows) {
const checkpoint = checkpointByChain.get(key);
if (checkpoint && !verifyAuditCheckpoint(checkpoint, options.secret)) {
invalidCheckpointChains.add(key);
continue;
}
if (options.allowPartialPrefix) {
initialPreviousHashes.set(key, first.previousHash);
} else if (checkpoint) {
if (first.previousHash !== checkpoint.lastDeletedEventHash) {
invalidCheckpointChains.add(key);
} else {
initialPreviousHashes.set(key, checkpoint.lastDeletedEventHash);
}
} else {
initialPreviousHashes.set(key, null);
}
}
return { initialPreviousHashes, invalidCheckpointChains };
}
export type PruneAuditChainBatchResult = {
tenantId: string | null;
deletedCount: number;
hasMore: boolean;
checkpointMac: string | null;
};
export async function pruneAuditChainBatch(
tenantId: string | null,
threshold: Date,
options: {
batchSize?: number;
now?: Date;
secret?: string | null;
client?: AuditRetentionClient;
} = {},
): Promise<PruneAuditChainBatchResult> {
const batchSize = Math.max(1, Math.min(options.batchSize ?? 1_000, 5_000));
const client = options.client ?? (getDbClient() as unknown as AuditRetentionClient);
return client.$transaction(async (tx) => {
await acquireAuditChainLock(tx, tenantId);
const candidates = await tx.auditEvent.findMany({
where: { tenantId, createdAt: { lt: threshold } },
orderBy: [{ createdAt: "asc" }, { id: "asc" }],
take: batchSize,
select: {
id: true,
createdAt: true,
tenantId: true,
actorType: true,
actorId: true,
actorEmail: true,
actorIp: true,
actorUserAgent: true,
action: true,
targetType: true,
targetId: true,
requestId: true,
sourceModule: true,
outcome: true,
dataSensitivity: true,
regulatoryScope: true,
metadata: true,
previousHash: true,
eventHash: true,
},
});
if (candidates.length === 0) {
return { tenantId, deletedCount: 0, hasMore: false, checkpointMac: null };
}
const chainKey = auditChainKey(tenantId);
const checkpointHead = await tx.auditChainCheckpointHead.findUnique({
where: { chainKey },
select: { checkpointId: true },
});
const latestCheckpoint = checkpointHead
? await tx.auditChainCheckpoint.findUnique({ where: { id: checkpointHead.checkpointId } })
: await tx.auditChainCheckpoint.findFirst({
where: { chainKey },
orderBy: [{ createdAt: "desc" }, { id: "desc" }],
});
if (latestCheckpoint && !verifyAuditCheckpoint(latestCheckpoint, options.secret)) {
throw new AuditChainCheckpointError(`Audit checkpoint authentication failed for ${chainKey}.`);
}
const initialPreviousHash = latestCheckpoint?.lastDeletedEventHash ?? null;
const chainEvents = candidates.map((row) => ({
...row,
createdAt: row.createdAt.toISOString(),
}));
const verified = verifyAuditChain(chainEvents, { secret: options.secret, initialPreviousHash });
if (!verified.ok) {
throw new AuditChainCheckpointError(
`Refusing to prune broken audit chain ${chainKey} at ${verified.firstBreak?.eventId ?? "unknown"}.`,
);
}
const last = candidates[candidates.length - 1]!;
const keysetAfter = {
OR: [
{ createdAt: { gt: last.createdAt } },
{ createdAt: last.createdAt, id: { gt: last.id } },
],
};
const firstRetained = await tx.auditEvent.findFirst({
where: { tenantId, ...keysetAfter },
orderBy: [{ createdAt: "asc" }, { id: "asc" }],
select: { id: true, previousHash: true, eventHash: true },
});
if (firstRetained?.eventHash !== null && firstRetained?.eventHash !== undefined && firstRetained.previousHash !== last.eventHash) {
throw new AuditChainCheckpointError(
`Refusing to prune discontinuous audit chain ${chainKey} before ${firstRetained.id}.`,
);
}
const nextExpired = await tx.auditEvent.findFirst({
where: { tenantId, createdAt: { lt: threshold }, ...keysetAfter },
orderBy: [{ createdAt: "asc" }, { id: "asc" }],
select: { id: true, previousHash: true, eventHash: true },
});
const checkpointWithoutMac: Omit<AuditChainCheckpointRecord, "checkpointMac"> = {
id: randomUUID(),
createdAt: options.now ?? new Date(),
chainKey,
tenantId,
deletedThroughAt: last.createdAt,
lastDeletedEventId: last.id,
lastDeletedEventHash: last.eventHash,
deletedCount: candidates.length,
previousCheckpointMac: latestCheckpoint?.checkpointMac ?? null,
};
const checkpointMac = computeAuditCheckpointMac(checkpointWithoutMac, options.secret);
await tx.auditChainCheckpoint.create({ data: { ...checkpointWithoutMac, checkpointMac } });
await tx.auditChainCheckpointHead.upsert({
where: { chainKey: checkpointWithoutMac.chainKey },
create: {
chainKey: checkpointWithoutMac.chainKey,
tenantId,
checkpointId: checkpointWithoutMac.id,
checkpointMac,
updatedAt: checkpointWithoutMac.createdAt,
},
update: {
tenantId,
checkpointId: checkpointWithoutMac.id,
checkpointMac,
updatedAt: checkpointWithoutMac.createdAt,
},
});
const deletion = await tx.auditEvent.deleteMany({
where: { id: { in: candidates.map((candidate) => candidate.id) } },
});
if (deletion.count !== candidates.length) {
throw new AuditChainCheckpointError(
`Audit retention deleted ${deletion.count} of ${candidates.length} checkpointed events for ${chainKey}.`,
);
}
return {
tenantId,
deletedCount: deletion.count,
hasMore: nextExpired !== null,
checkpointMac,
};
});
}
function compareAuditRows(left: AuditVerificationRow, right: AuditVerificationRow): number {
const time = new Date(left.createdAt).getTime() - new Date(right.createdAt).getTime();
return time !== 0 ? time : left.id.localeCompare(right.id);
}