/** * Phase 10 Task #67 — Audit-Event retention worker. * * Walks every tenant on a daily cron, looks up the tenant's retention * window (plan-based default; configurable per-tenant via an override * JSON in a future task), and deletes AuditEvent rows older than the * window. Deletions are themselves audited as a system-action event so * the cleanup itself is traceable — see * docs/features/compliance-audit.md. * * Deliberately host-agnostic: the worker bootstrap (apps/worker/src/index.ts) * supplies the seams (tenantLister, eventDeleter, auditWriter) so this * file is trivially unit-testable without a real database. */ export const DEFAULT_AUDIT_RETENTION_DAYS = 365; // baseline / "none" scope export const SOC2_AUDIT_RETENTION_DAYS = 7 * 365; // SOC2 + HIPAA: 7y export const GDPR_AUDIT_RETENTION_DAYS = 6 * 365; // GDPR: 6y // AK-P3 AP-2 — cron wiring. Mirrors plugin-audit-retention so the worker // bootstrap can install a nightly scheduler for the AuditEvent sweep. export const AUDIT_RETENTION_QUEUE = "audit-retention" as const; export const AUDIT_RETENTION_JOB_ID = "audit-retention" as const; /** Nightly at 03:30 UTC (offset from plugin-audit-retention's 03:00). */ export const AUDIT_RETENTION_CRON_DEFAULT = "30 3 * * *" as const; export type AuditRetentionEnv = Readonly>; /** * Install (or replace) the nightly AuditEvent-retention schedule on a * BullMQ-like queue. Idempotent via a stable scheduler key. Cron pattern * overridable via `AUDIT_RETENTION_CRON`. */ export async function registerAuditRetentionCron( queue: { upsertJobScheduler: ( schedulerId: string, options: { pattern: string }, template: { name: string; data?: Record }, ) => Promise; }, env: AuditRetentionEnv | undefined = process.env, ): Promise<{ pattern: string }> { const pattern = env?.AUDIT_RETENTION_CRON?.trim() || AUDIT_RETENTION_CRON_DEFAULT; await queue.upsertJobScheduler( AUDIT_RETENTION_JOB_ID, { pattern }, { name: AUDIT_RETENTION_JOB_ID, data: { task: AUDIT_RETENTION_JOB_ID } }, ); return { pattern }; } export type AuditRetentionPolicy = { /** Hard cap in days. Events older than this are pruned. */ retentionDays: number; /** Free-form label for log lines (`gdpr` | `soc2` | `plan:enterprise` | …). */ source: string; }; export type AuditRetentionTenant = { tenantId: string; /** Highest regulatoryScope used by events for this tenant. */ regulatoryScopes: ReadonlyArray; }; export type AuditRetentionInput = { /** Reference "now" — defaults to `new Date()`. Injected for tests. */ now?: Date; /** List tenants (each with the regulatoryScopes ever used by their events). */ tenantLister: () => Promise>; /** Delete events with createdAt < threshold for tenantId. Returns row count. */ eventDeleter: (tenantId: string, threshold: Date) => Promise; /** Optional audit writer for the meta-audit (cleanup itself). */ auditWriter?: (input: { tenantId: string; deletedCount: number; threshold: Date; policy: AuditRetentionPolicy }) => Promise; /** Logger seam. */ logger?: { info: (fields: Record, msg: string) => void; error?: (fields: Record, msg: string) => void }; /** Optional override for plan-resolved policy per tenant. */ policyResolver?: (tenant: AuditRetentionTenant) => AuditRetentionPolicy; }; export function resolveAuditRetentionPolicy(tenant: AuditRetentionTenant): AuditRetentionPolicy { const scopes = new Set(tenant.regulatoryScopes.map((s) => s.toLowerCase())); if (scopes.has("soc2") || scopes.has("hipaa")) { return { retentionDays: SOC2_AUDIT_RETENTION_DAYS, source: scopes.has("hipaa") ? "hipaa" : "soc2" }; } if (scopes.has("gdpr")) { return { retentionDays: GDPR_AUDIT_RETENTION_DAYS, source: "gdpr" }; } return { retentionDays: DEFAULT_AUDIT_RETENTION_DAYS, source: "default" }; } export type AuditRetentionResult = { inspectedTenants: number; deletedRows: number; failures: Array<{ tenantId: string; error: string }>; }; /** * Run the retention sweep across every tenant. Caller (cron bootstrap) * decides scheduling — this function is a single pass. */ export async function runAuditRetentionJob(input: AuditRetentionInput): Promise { const now = input.now ?? new Date(); const tenants = await input.tenantLister(); let deletedRows = 0; const failures: AuditRetentionResult["failures"] = []; for (const tenant of tenants) { try { const policy = (input.policyResolver ?? resolveAuditRetentionPolicy)(tenant); const threshold = new Date(now.getTime() - policy.retentionDays * 86_400_000); const count = await input.eventDeleter(tenant.tenantId, threshold); deletedRows += count; input.logger?.info({ tenantId: tenant.tenantId, deletedCount: count, retentionDays: policy.retentionDays, policySource: policy.source }, "audit.retention.tenant.swept"); if (count > 0 && input.auditWriter) { await input.auditWriter({ tenantId: tenant.tenantId, deletedCount: count, threshold, policy }); } } catch (error) { const message = error instanceof Error ? error.message : String(error); failures.push({ tenantId: tenant.tenantId, error: message }); input.logger?.error?.({ tenantId: tenant.tenantId, error: message }, "audit.retention.tenant.failed"); } } input.logger?.info({ inspected: tenants.length, deletedRows, failures: failures.length }, "audit.retention.complete"); return { inspectedTenants: tenants.length, deletedRows, failures }; }