feat(audit): tamper-evident logging, alerting, retention and compliance reports (#396)

[sandrawillow001-afk]

Coordination note. Issue #396 is currently assigned to @itsjoetruthofficial-lang. This PR implements the same subject matter; please coordinate with them before merging so the effort is not duplicated.

Closes #396.

What already existed

The HTTP audit path (services/auditService.ts, routes/audit.ts, middleware/sensitiveAudit.ts) already had a hash chain, query/export endpoints and a retention policy object, and src/audit/* had an immutable logger plus a chain verifier. Re-checking #396's acceptance criteria against that code left four genuine gaps.

Gaps closed

Criterion	Before	Now
Real-time alerting for critical events	Only tamper alerts from the chain verifier	audit/alerting.ts — declarative rules, severity thresholds, sliding-window de-duplication, log + optional webhook sinks
Retention with archival policy	Policy object with no archival	audit/retention.ts — hot/archive/purge tiers, append-only NDJSON archives with manifests and payload hashes
Compliance reporting (SOC2, PCI-DSS fields)	Nothing	audit/compliance-report.ts — SOC2 TSC + PCI-DSS v4 req. 10 control mapping, per-control evidence, 10.3 field completeness
Edge case: log injection, storage cost	Untrusted detail values logged verbatim; evicting entries broke verifyIntegrity()	audit/event-schema.ts sanitises CR/LF, control characters and ANSI escapes; CSV export neutralises formulas; a chain anchor keeps verification valid after eviction

src/audit/event-schema.ts also adds the canonical validated event schema (actor, action, resource, timestamp, outcome, origin) that the issue asks for.

API

• GET /api/v1/audit/alerts — recent alerts + counts by severity
• GET /api/v1/audit/compliance/report — ?framework=SOC2|PCI-DSS, ?from=, ?to=, ?format=csv
• GET /api/v1/audit/retention/tiers, GET /api/v1/audit/archives
• POST /api/v1/audit/retention/archive?confirm=true
• POST /api/v1/audit/log now validates against the canonical schema (400 with issue details)

Verification

cd backend
npx vitest run src/audit src/services/__tests__/auditService.test.ts   # 79 passed
npx vitest run src/middleware/__tests__/audit.test.ts \
  src/middleware/__tests__/sensitiveAudit.test.ts \
  src/middleware/__tests__/brute-force.test.ts \
  src/routes/__tests__/token-refresh.test.ts \
  src/routes/__tests__/auth-lockout.test.ts                            # 86 passed, no regressions
npx eslint src/audit src/services/auditService.ts src/routes/audit.ts  # clean
npx tsc --noEmit | grep -c 'src/audit\|services/auditService\|routes/audit'  # 0

Note on typecheck. npx tsc --noEmit reports ~1022 pre-existing errors repo-wide (largely @prisma/client not generated in this environment). None are in the files this PR touches; the count was 1026 before these changes.

⚠️ This PR depends on the package.json fix (separate PR) to install dependencies at all.

---

🤖 Generated with Codebuff

[vercel]

@sandrawillow001-afk is attempting to deploy a commit to the smartdevs17's projects Team on Vercel.

A member of the Team first needs to authorize it.