Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/worker/src/jobs/audit-event-persist.ts
T

466 lines
16 KiB
TypeScript

/**
* Phase 10 Task #67 — Audit-event outbox handler.
*
* Subscribes to the `outbox.audit` BullMQ queue (populated by the
* outbox dispatcher in apps/worker/src/outbox/dispatcher.ts) and
* inserts the AuditEvent row into Postgres.
*
* The hash chain is computed inside a short Prisma transaction:
* - acquire a tenant/platform PostgreSQL advisory transaction lock
* - authenticate and read the O(1) persistent chain head
* - compute the new event's eventHash
* - insert the event and atomically advance the authenticated head
*
* The advisory lock is shared with direct writers and retention, so N
* parallel BullMQ workers cannot fork a tenant or platform chain.
*
* Authority and idempotency: Redis is transport only. Before inserting an
* AuditEvent the consumer proves the exact tenant/generation/payload/dispatch
* key/lease against the durable OutboxEvent, claims that generation with a
* CAS, then commits the AuditEvent and terminal DONE receipt atomically.
*/
import { randomUUID } from "node:crypto";
import { computeAuditHash, type AuditHashPayload } from "@hivegrid/db/audit-hash";
import {
acquireAuditChainLock,
auditChainKey,
computeAuditChainHeadMac,
verifyAuditChainHead,
verifyAuditCheckpoint,
type AuditChainHeadRecord,
type AuditChainCheckpointRecord,
} from "@hivegrid/db/audit-chain-checkpoint.server";
import {
buildAuditEventCreateData,
type AuditEventCreateData,
type AuditEventInput,
} from "@hivegrid/db/audit-events.server";
export const AUDIT_EVENT_OUTBOX_QUEUE = "outbox.audit" as const;
const AUDIT_OUTBOX_CONSUMER_LEASE_MS = 5 * 60 * 1_000;
export interface AuditEventPersistLogger {
info?: (record: Record<string, unknown>, message?: string) => void;
warn?: (record: Record<string, unknown>, message?: string) => void;
error: (record: Record<string, unknown>, message?: string) => void;
}
export interface AuditEventPersistTxClient {
$queryRaw<T = unknown>(query: TemplateStringsArray, ...values: unknown[]): Promise<T>;
auditEvent: {
findFirst(args: {
where: { tenantId: string | null; eventHash: { not: null } };
orderBy: Array<{ createdAt: "desc" } | { id: "desc" }>;
select: { eventHash: true; createdAt: true };
}): Promise<{ eventHash: string | null; createdAt: Date } | null>;
create(args: {
data: AuditEventCreateData & { id: string; createdAt: Date; previousHash: string | null; eventHash: string };
}): Promise<{ id: string; eventHash: string }>;
};
auditChainCheckpoint: {
findFirst(args: {
where: { chainKey: string };
orderBy: Array<{ createdAt: "desc" } | { id: "desc" }>;
}): Promise<AuditChainCheckpointRecord | null>;
findUnique(args: { where: { id: string } }): Promise<AuditChainCheckpointRecord | null>;
};
auditChainCheckpointHead: {
findUnique(args: {
where: { chainKey: string };
select: { checkpointId: true };
}): Promise<{ checkpointId: string } | null>;
};
auditChainHead: {
findUnique(args: { where: { chainKey: string } }): Promise<AuditChainHeadRecord | null>;
upsert(args: {
where: { chainKey: string };
create: AuditChainHeadRecord;
update: Omit<AuditChainHeadRecord, "chainKey">;
}): Promise<unknown>;
};
outboxEvent: {
findFirst(args: {
where: {
id: string;
tenantId: string | null;
eventType: "audit.event.create";
deliveryGeneration: number;
};
select: {
id: true;
tenantId: true;
eventType: true;
payload: true;
status: true;
deliveryGeneration: true;
dispatchKey: true;
lockedUntil: true;
};
}): Promise<{
id: string;
tenantId: string | null;
eventType: string;
payload: unknown;
status: "PENDING" | "PROCESSING" | "DONE" | "FAILED" | "CANCELLED";
deliveryGeneration: number;
dispatchKey: string | null;
lockedUntil: Date | null;
} | null>;
updateMany(args: {
where: {
id: string;
tenantId: string | null;
eventType: "audit.event.create";
deliveryGeneration: number;
dispatchKey: string | null;
status: "PROCESSING";
lockedUntil: Date;
payload: { equals: unknown };
};
data:
| { lockedUntil: Date }
| { status: "DONE"; processedAt: Date; lastError: null; lockedUntil: null };
}): Promise<{ count: number }>;
};
}
export interface AuditEventPersistTransactionRunner {
/**
* Run `fn` inside a Prisma transaction. Production additionally uses
* serializable isolation; the per-chain advisory lock is the primary
* cross-writer serialization primitive.
*/
<T>(fn: (tx: AuditEventPersistTxClient) => Promise<T>): Promise<T>;
}
export interface AuditEventPersistDependencies {
readonly runInTransaction: AuditEventPersistTransactionRunner;
readonly logger?: AuditEventPersistLogger;
/**
* Override the hash-chain secret resolution for tests. Production
* leaves this undefined so the helper reads `process.env.AUDIT_CHAIN_SECRET`.
*/
readonly secret?: string | null;
/** Clock override for durable lease checks and deterministic tests. */
readonly now?: () => Date;
}
export class AuditEventPersistJobError extends Error {
override readonly name = "AuditEventPersistJobError";
readonly code: "INVALID_PAYLOAD" | "INVALID_EVENT_TYPE" | "MISSING_ACTION" | "OUTBOX_PROOF_INVALID";
constructor(message: string, code: AuditEventPersistJobError["code"]) {
super(message);
this.code = code;
}
}
export interface AuditEventPersistJobData {
readonly outboxEventId: string;
readonly tenantId: string | null;
readonly eventType: "audit.event.create";
readonly dispatchKey: string | null;
readonly deliveryGeneration: number;
readonly lockedUntil: Date;
readonly rawPayload: Readonly<Record<string, unknown>>;
readonly payload: AuditEventCreateData;
}
export interface AuditEventPersistResult {
readonly persisted: true;
readonly auditEventId: string;
readonly eventHash: string;
}
export function parseAuditEventPersistJob(data: unknown): AuditEventPersistJobData {
if (!data || typeof data !== "object" || Array.isArray(data)) {
throw new AuditEventPersistJobError("audit-event persist job missing data envelope", "INVALID_PAYLOAD");
}
const envelope = data as Record<string, unknown>;
const eventType = typeof envelope.eventType === "string" ? envelope.eventType : "";
if (eventType !== "audit.event.create") {
throw new AuditEventPersistJobError(
`audit-event persist job rejected eventType ${JSON.stringify(eventType)}`,
"INVALID_EVENT_TYPE"
);
}
const rawPayload = envelope.payload;
if (!rawPayload || typeof rawPayload !== "object") {
throw new AuditEventPersistJobError("audit-event persist job missing payload", "INVALID_PAYLOAD");
}
if (Array.isArray(rawPayload)) {
throw new AuditEventPersistJobError("audit-event persist job payload must be an object", "INVALID_PAYLOAD");
}
const inner = rawPayload as Record<string, unknown>;
const action = typeof inner.action === "string" ? inner.action.trim() : "";
if (action.length === 0) {
throw new AuditEventPersistJobError("audit-event persist job missing action", "MISSING_ACTION");
}
// Re-run normalization in case the producer emitted an older payload
// shape — defensive. `buildAuditEventCreateData` is idempotent.
const normalized = buildAuditEventCreateData(inner as unknown as AuditEventInput);
const outboxEventId = parseIdentifier(envelope.outboxEventId);
const tenantId = parseNullableIdentifier(envelope, "tenantId");
const dispatchKey = parseNullableDispatchKey(envelope);
const deliveryGeneration = envelope.deliveryGeneration;
const lockedUntil = parseLease(envelope.lockedUntil);
if (
!outboxEventId ||
tenantId === undefined ||
dispatchKey === undefined ||
!Number.isSafeInteger(deliveryGeneration) ||
(deliveryGeneration as number) < 0 ||
!lockedUntil
) {
throw new AuditEventPersistJobError("audit-event persist job has no exact outbox identity", "INVALID_PAYLOAD");
}
if (normalized.tenantId !== null && normalized.tenantId !== tenantId) {
throw new AuditEventPersistJobError("audit-event tenant does not match its outbox envelope", "INVALID_PAYLOAD");
}
return {
outboxEventId,
tenantId,
eventType: "audit.event.create",
dispatchKey,
deliveryGeneration: deliveryGeneration as number,
lockedUntil,
rawPayload: inner,
payload: normalized,
};
}
function parseIdentifier(value: unknown): string | null {
if (typeof value !== "string") return null;
const normalized = value.trim();
return normalized.length > 0 && normalized.length <= 191 && !normalized.includes("\u0000") ? normalized : null;
}
function parseNullableIdentifier(
envelope: Readonly<Record<string, unknown>>,
key: "tenantId",
): string | null | undefined {
if (!Object.hasOwn(envelope, key)) return undefined;
if (envelope[key] === null) return null;
return parseIdentifier(envelope[key]) ?? undefined;
}
function parseNullableDispatchKey(envelope: Readonly<Record<string, unknown>>): string | null | undefined {
if (!Object.hasOwn(envelope, "dispatchKey")) return undefined;
if (envelope.dispatchKey === null) return null;
if (typeof envelope.dispatchKey !== "string") return undefined;
return /^[A-Za-z0-9._:-]{1,256}$/u.test(envelope.dispatchKey) ? envelope.dispatchKey : undefined;
}
function parseLease(value: unknown): Date | null {
const parsed = value instanceof Date ? new Date(value.getTime()) : typeof value === "string" ? new Date(value) : null;
return parsed && Number.isFinite(parsed.getTime()) ? parsed : null;
}
function toHashPayload(data: AuditEventCreateData, id: string, createdAt: Date): AuditHashPayload {
return {
id,
createdAt: createdAt.toISOString(),
tenantId: data.tenantId,
actorType: data.actorType,
actorId: data.actorId,
actorEmail: data.actorEmail,
actorIp: data.actorIp,
actorUserAgent: data.actorUserAgent,
action: data.action,
targetType: data.targetType,
targetId: data.targetId,
requestId: data.requestId,
sourceModule: data.sourceModule,
outcome: data.outcome,
dataSensitivity: data.dataSensitivity,
regulatoryScope: data.regulatoryScope,
metadata: data.metadata,
};
}
export async function runAuditEventPersistJob(
data: unknown,
deps: AuditEventPersistDependencies
): Promise<AuditEventPersistResult> {
const job = parseAuditEventPersistJob(data);
const payload = job.payload;
const result = await deps.runInTransaction(async (tx) => {
const durable = await tx.outboxEvent.findFirst({
where: {
id: job.outboxEventId,
tenantId: job.tenantId,
eventType: job.eventType,
deliveryGeneration: job.deliveryGeneration,
},
select: {
id: true,
tenantId: true,
eventType: true,
payload: true,
status: true,
deliveryGeneration: true,
dispatchKey: true,
lockedUntil: true,
},
});
const observedAt = deps.now?.() ?? new Date();
if (
!durable ||
durable.status !== "PROCESSING" ||
durable.dispatchKey !== job.dispatchKey ||
!durable.lockedUntil ||
durable.lockedUntil.getTime() !== job.lockedUntil.getTime() ||
durable.lockedUntil.getTime() <= observedAt.getTime() ||
!sameCanonicalJson(durable.payload, job.rawPayload)
) {
throw invalidOutboxProof();
}
const claimedLease = new Date(
Math.max(
observedAt.getTime() + AUDIT_OUTBOX_CONSUMER_LEASE_MS,
durable.lockedUntil.getTime() + 1,
),
);
const claimed = await tx.outboxEvent.updateMany({
where: {
id: job.outboxEventId,
tenantId: job.tenantId,
eventType: job.eventType,
deliveryGeneration: job.deliveryGeneration,
dispatchKey: job.dispatchKey,
status: "PROCESSING",
lockedUntil: durable.lockedUntil,
payload: { equals: job.rawPayload },
},
data: { lockedUntil: claimedLease },
});
if (claimed.count !== 1) throw invalidOutboxProof();
await acquireAuditChainLock(tx, payload.tenantId);
const key = auditChainKey(payload.tenantId);
const head = await tx.auditChainHead.findUnique({ where: { chainKey: key } });
if (head && !verifyAuditChainHead(head, deps.secret)) {
throw new Error(`Audit chain-head authentication failed for ${key}.`);
}
let previousHash = head?.eventHash ?? null;
let previousCreatedAt = head?.eventCreatedAt ?? null;
if (!previousHash) {
const prior = await tx.auditEvent.findFirst({
where: { tenantId: payload.tenantId, eventHash: { not: null } },
orderBy: [{ createdAt: "desc" }, { id: "desc" }],
select: { eventHash: true, createdAt: true },
});
previousHash = prior?.eventHash ?? null;
previousCreatedAt = prior?.createdAt ?? null;
}
if (!previousHash) {
const checkpointHead = await tx.auditChainCheckpointHead.findUnique({
where: { chainKey: key },
select: { checkpointId: true },
});
const checkpoint = checkpointHead
? await tx.auditChainCheckpoint.findUnique({ where: { id: checkpointHead.checkpointId } })
: await tx.auditChainCheckpoint.findFirst({
where: { chainKey: key },
orderBy: [{ createdAt: "desc" }, { id: "desc" }],
});
if (checkpoint) {
if (!verifyAuditCheckpoint(checkpoint, deps.secret)) {
throw new Error(`Audit checkpoint authentication failed for ${checkpoint.chainKey}.`);
}
previousHash = checkpoint.lastDeletedEventHash;
previousCreatedAt = checkpoint.deletedThroughAt;
}
}
const id = randomUUID();
const now = deps.now?.() ?? new Date();
const createdAt = previousCreatedAt && now.getTime() <= previousCreatedAt.getTime()
? new Date(previousCreatedAt.getTime() + 1)
: now;
const eventHash = computeAuditHash({
previousHash,
payload: toHashPayload(payload, id, createdAt),
secret: deps.secret,
version: "hmac-v2",
});
const inserted = await tx.auditEvent.create({
data: { ...payload, id, createdAt, previousHash, eventHash },
});
const headWithoutMac: Omit<AuditChainHeadRecord, "headMac"> = {
chainKey: key,
tenantId: payload.tenantId,
eventId: id,
eventHash,
eventCreatedAt: createdAt,
};
const headMac = computeAuditChainHeadMac(headWithoutMac, deps.secret);
await tx.auditChainHead.upsert({
where: { chainKey: key },
create: { ...headWithoutMac, headMac },
update: { tenantId: payload.tenantId, eventId: id, eventHash, eventCreatedAt: createdAt, headMac },
});
const receipt = await tx.outboxEvent.updateMany({
where: {
id: job.outboxEventId,
tenantId: job.tenantId,
eventType: job.eventType,
deliveryGeneration: job.deliveryGeneration,
dispatchKey: job.dispatchKey,
status: "PROCESSING",
lockedUntil: claimedLease,
payload: { equals: job.rawPayload },
},
data: {
status: "DONE",
processedAt: createdAt,
lastError: null,
lockedUntil: null,
},
});
if (receipt.count !== 1) throw invalidOutboxProof();
return { auditEventId: inserted.id, eventHash };
});
deps.logger?.info?.(
{
component: "audit-event-persist",
tenantId: payload.tenantId,
action: payload.action,
auditEventId: result.auditEventId,
outboxEventId: job.outboxEventId,
},
"audit-event persisted via outbox"
);
return { persisted: true, auditEventId: result.auditEventId, eventHash: result.eventHash };
}
function invalidOutboxProof(): AuditEventPersistJobError {
return new AuditEventPersistJobError(
"audit-event persist job does not match an active durable outbox generation",
"OUTBOX_PROOF_INVALID",
);
}
function sameCanonicalJson(left: unknown, right: unknown): boolean {
try {
return JSON.stringify(canonicalJson(left)) === JSON.stringify(canonicalJson(right));
} catch {
return false;
}
}
function canonicalJson(value: unknown): unknown {
if (value === null || typeof value === "string" || typeof value === "boolean") return value;
if (typeof value === "number" && Number.isFinite(value)) return value;
if (Array.isArray(value)) return value.map(canonicalJson);
if (!value || typeof value !== "object") throw new TypeError("Value is not canonical JSON");
return Object.fromEntries(
Object.keys(value as Record<string, unknown>)
.sort()
.map((key) => [key, canonicalJson((value as Record<string, unknown>)[key])]),
);
}