128 lines
5.6 KiB
TypeScript
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 };
|
|
}
|