Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,186 @@
|
||||
# Compliance-Audit-Export
|
||||
|
||||
Phase 10 Task #67. Tamper-evident, SOC2/HIPAA/GDPR-ready audit log with a
|
||||
self-service export UI for tenants and a system-wide export for platform
|
||||
admins.
|
||||
|
||||
## Overview
|
||||
|
||||
`AuditEvent` (`prisma/schema/core.prisma`) is the single normative store
|
||||
for privileged actions across the platform. Phase 10 extended the model
|
||||
with:
|
||||
|
||||
| Field | Purpose |
|
||||
| ----------------- | ---------------------------------------------------------- |
|
||||
| `actorEmail` | denormalized actor email for compliance reports |
|
||||
| `actorIp` | first-hop client IP (cf-connecting-ip / x-real-ip / xff) |
|
||||
| `actorUserAgent` | UA capped at 512 chars |
|
||||
| `sourceModule` | `auth` / `billing` / `admin` / `plugin:foo` |
|
||||
| `outcome` | `success` / `failure` / `blocked` |
|
||||
| `dataSensitivity` | `public` / `internal` / `confidential` / `pii` |
|
||||
| `regulatoryScope` | string[]: `gdpr` `hipaa` `soc2` `pci` |
|
||||
| `previousHash` | predecessor `eventHash` for the same tenant chain |
|
||||
| `eventHash` | HMAC-SHA-256 over canonical payload + previousHash |
|
||||
|
||||
Existing fields (`tenantId`, `actorId`, `actorType`, `action`,
|
||||
`targetType`, `targetId`, `requestId`, `metadata`) remain unchanged.
|
||||
|
||||
## Hash-Chain
|
||||
|
||||
Per-tenant chain: each tenant's events form an independent linked-list
|
||||
keyed by `previousHash`. Platform-level events (tenantId IS NULL) form
|
||||
their own chain.
|
||||
|
||||
```
|
||||
eventHash_n = HMAC-SHA-256(AUDIT_CHAIN_SECRET, eventHash_{n-1} || canonicalJSON(payload_n))
|
||||
```
|
||||
|
||||
`canonicalJSON` is the JSON encoding produced by
|
||||
`canonicalizeAuditPayload` in
|
||||
`packages/db/src/audit-hash.ts`: object keys sorted recursively,
|
||||
`undefined` dropped, arrays preserve order. Without
|
||||
`AUDIT_CHAIN_SECRET` the helper falls back to plain SHA-256 — still
|
||||
tamper-evident for read-only attackers but trivially forgeable.
|
||||
|
||||
`verifyAuditChain(events, { secret })` walks the chain oldest → newest
|
||||
and returns the first break with one of:
|
||||
|
||||
- `previous-hash-mismatch` — chain discontinuity (an event was inserted
|
||||
or deleted)
|
||||
- `hash-mismatch` — payload was modified in-place
|
||||
|
||||
## Auto-Capture
|
||||
|
||||
### API (Hono)
|
||||
|
||||
`apps/api/src/middleware/audit-context.ts` registers an AsyncLocalStorage
|
||||
binding on every request and exposes `getAuditContext()`. Deeper code
|
||||
(`createAuditEvent` calls in services) automatically picks up actor IP,
|
||||
user agent, request id without threading the request object.
|
||||
|
||||
```ts
|
||||
import { createAuditContextMiddleware } from "./middleware/audit-context.js";
|
||||
app.use("*", createAuditContextMiddleware());
|
||||
```
|
||||
|
||||
### Web (React-Router v7)
|
||||
|
||||
`apps/web/app/utils/audit/withAuditContext.ts` mirrors the API helper for
|
||||
loaders/actions:
|
||||
|
||||
```ts
|
||||
export const action = async (args: ActionFunctionArgs) =>
|
||||
withAuditContext(args, async () => {
|
||||
// ...createAuditEvent calls deeper in the stack pick up actor ctx
|
||||
});
|
||||
```
|
||||
|
||||
For ad-hoc reads `extractWebActorIp(request)` and
|
||||
`extractWebActorUserAgent(request)` are exported too.
|
||||
|
||||
## Export UI
|
||||
|
||||
Two routes ship:
|
||||
|
||||
- `/admin/audit-export` — platform admin, system-wide. Optional
|
||||
`tenantId` filter.
|
||||
- `/app/$tenant/settings/audit-export` — tenant self-service. tenantId
|
||||
is force-applied server-side; query-string spoofing is silently
|
||||
dropped.
|
||||
|
||||
Both stream a CSV up to 50 000 rows (`AUDIT_EXPORT_MAX_ROWS`). The
|
||||
**first line** of the CSV is the `verifyAuditChain` integrity header so
|
||||
the download itself is the auditor evidence package:
|
||||
|
||||
```
|
||||
# verifyAuditChain: ok=true inspected=12345 firstBreakId=- reason=-
|
||||
id,createdAt,tenantId,actorType,actorId,…
|
||||
```
|
||||
|
||||
The HTTP response also carries an `X-Audit-Chain-Status: ok|broken`
|
||||
header so a programmatic client can branch without parsing the CSV.
|
||||
|
||||
Filters:
|
||||
|
||||
- `from` / `to` (ISO date, inclusive UTC range; max 1 year recommended)
|
||||
- `regulatoryScope` (multi)
|
||||
- `actorType` (`user` / `admin` / `api_key` / `system` / `plugin`)
|
||||
- `outcome` (`success` / `failure` / `blocked`)
|
||||
- `tenantId` (admin variant only)
|
||||
|
||||
CSV cells with commas, quotes or newlines are RFC-4180 escaped; arrays
|
||||
join with `|`; JSON metadata is stringified.
|
||||
|
||||
## Retention
|
||||
|
||||
`apps/worker/src/jobs/audit-retention.ts` exposes `runAuditRetentionJob`
|
||||
which the worker host wires to a daily cron.
|
||||
|
||||
Plan-based defaults (`resolveAuditRetentionPolicy`):
|
||||
|
||||
| Regulatory scope on tenant events | Retention |
|
||||
| --------------------------------- | --------- |
|
||||
| `soc2` or `hipaa` | 7 years |
|
||||
| `gdpr` | 6 years |
|
||||
| none | 1 year |
|
||||
|
||||
Every non-empty sweep emits a meta-audit (`audit.retention.swept`) so
|
||||
the cleanup itself is traceable.
|
||||
|
||||
## Operator Procedures
|
||||
|
||||
### Bootstrap
|
||||
|
||||
1. Generate a secret: `openssl rand -base64 32`.
|
||||
2. Set `AUDIT_CHAIN_SECRET=<value>` in Coolify (platform-wide, never
|
||||
per-tenant).
|
||||
3. Apply the Prisma migration
|
||||
`20260517180000_10_audit_event_compliance`.
|
||||
|
||||
### Self-service export (tenant admin)
|
||||
|
||||
1. Navigate to `Settings → Audit Export`.
|
||||
2. Pick date range + filters.
|
||||
3. Click *Download CSV*.
|
||||
4. Verify the first line shows `ok=true`. If `ok=false`, contact
|
||||
platform support — chain integrity has been compromised.
|
||||
|
||||
### Forensic verify (platform admin)
|
||||
|
||||
```
|
||||
# In a node REPL with the export CSV:
|
||||
const { verifyAuditChain } = await import("@toolctrl/db/audit-hash");
|
||||
// load events from CSV/DB, then:
|
||||
verifyAuditChain(events, { secret: process.env.AUDIT_CHAIN_SECRET });
|
||||
```
|
||||
|
||||
### Tampering detection drill
|
||||
|
||||
```
|
||||
psql ... -c "UPDATE \"AuditEvent\" SET metadata = '{\"tampered\":true}' WHERE id = '<id>'"
|
||||
```
|
||||
|
||||
Re-export the tenant — the integrity header now reports
|
||||
`ok=false reason=hash-mismatch firstBreakId=<id>`.
|
||||
|
||||
## Roadmap
|
||||
|
||||
- Admin per-tenant retention-policy override JSON
|
||||
- S3-glacier auto-archive before retention delete
|
||||
- Pre-built SOC2 / GDPR / HIPAA report templates (PDF with signature
|
||||
hash)
|
||||
- CLI: `pnpm audit:verify-chain --tenant <id>` direct DB walker
|
||||
- Outbox-driven audit writes for transactional consistency with
|
||||
business writes (Phase 03 #42 integration)
|
||||
|
||||
## Related
|
||||
|
||||
- `prisma/migrations/20260517180000_10_audit_event_compliance/`
|
||||
- `packages/db/src/audit-hash.ts` — chain helpers
|
||||
- `packages/db/src/audit-events.server.ts` — single write-path
|
||||
- `apps/api/src/middleware/audit-context.ts` — API auto-capture
|
||||
- `apps/web/app/utils/audit/withAuditContext.ts` — web auto-capture
|
||||
- `apps/web/app/routes/admin/audit-export.tsx` — admin export UI
|
||||
- `apps/web/app/routes/app.$tenant/settings/audit-export.tsx` — tenant
|
||||
export UI
|
||||
- `apps/worker/src/jobs/audit-retention.ts` — retention worker
|
||||
Reference in new issue
Block a user