Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/worker/src/jobs/audit-retention.ts
T
2026-07-08 16:15:37 +02:00

128 lines
5.6 KiB
TypeScript

/**
* 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<Record<string, string | undefined>>;
/**
* 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<string, unknown> },
) => Promise<unknown>;
},
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<string>;
};
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<ReadonlyArray<AuditRetentionTenant>>;
/** Delete events with createdAt < threshold for tenantId. Returns row count. */
eventDeleter: (tenantId: string, threshold: Date) => Promise<number>;
/** Optional audit writer for the meta-audit (cleanup itself). */
auditWriter?: (input: { tenantId: string; deletedCount: number; threshold: Date; policy: AuditRetentionPolicy }) => Promise<void>;
/** Logger seam. */
logger?: { info: (fields: Record<string, unknown>, msg: string) => void; error?: (fields: Record<string, unknown>, 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<AuditRetentionResult> {
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 };
}