/** * 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, message?: string) => void; warn?: (record: Record, message?: string) => void; error: (record: Record, message?: string) => void; } export interface AuditEventPersistTxClient { $queryRaw(query: TemplateStringsArray, ...values: unknown[]): Promise; 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; findUnique(args: { where: { id: string } }): Promise; }; auditChainCheckpointHead: { findUnique(args: { where: { chainKey: string }; select: { checkpointId: true }; }): Promise<{ checkpointId: string } | null>; }; auditChainHead: { findUnique(args: { where: { chainKey: string } }): Promise; upsert(args: { where: { chainKey: string }; create: AuditChainHeadRecord; update: Omit; }): Promise; }; 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. */ (fn: (tx: AuditEventPersistTxClient) => Promise): Promise; } 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>; 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; 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; 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>, 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>): 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 { 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 = { 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) .sort() .map((key) => [key, canonicalJson((value as Record)[key])]), ); }