feat(audit): AuditEvent table and write path for existing state transitions

[zainabwahab-eth]

Closes #43

What changed

AuditEvent model (ARCHITECTURE.md §4.10, migration 20261017212335_add_audit_event). Fields: actorUserId, actorRole, entityType, entityId, action, fromState, toState, requestId, metadata (jsonb), createdAt. Indexes on (entityType, entityId, createdAt), (actorUserId, createdAt) and (createdAt, id).

• Append-only, enforced twice. There is no update or delete path in code (the repository exports only insertAuditEvent and findAuditEvents, and a test asserts exactly that). In the database, a BEFORE UPDATE OR DELETE row trigger and a BEFORE TRUNCATE statement trigger reject mutation. A future retention policy has to drop and recreate them in its own reviewed migration.
• No foreign keys, on purpose. An ON DELETE action would have to rewrite audit rows, which the trigger forbids. RESTRICT would let the audit trail block account lifecycle (e.g. [Phase 8] Account deletion with clinical-record retention: anonymise identity, keep the audit trail #41's purge). Ids are recorded as facts.

audit module (routes/controllers/services/repositories):

• record(tx, actor, event) refuses the root Prisma client at runtime, so it can only run inside the transaction of the change it describes. If the change rolls back, so does its event.
• Metadata must be a flat map of at most 16 scalars, with strings up to 200 chars. Any key that could carry personal or secret data (name, email, phone, dob, notes, intake, symptom, password, secret, token, key, body, payload, ...) is refused. Callers pass only ids and codes.
• Request ids: a new middleware keeps a well-formed inbound X-Request-Id or mints a UUID, and echoes it on every response. Controllers pass auditActor(req) (user id, role, request id).

Wired transitions. States are taken from the real implementation, not invented:

Flow	Action	from → to	Where
Booking	appointment.booked	null → scheduled	third step inside bookSlot's existing transaction, after claimOpenSlot and the Appointment insert. The concurrency mechanism is untouched; race losers fail at step 1 and record nothing.
Doctor verification	doctor.verification_status_changed	previous → new	previous status read FOR UPDATE in the same transaction, so concurrent admins each record the real from-state. Setting the same status records nothing.
Payments	payment_intent.funded / .released / .refunded	created → escrowed, escrowed → released, escrowed → refunded	the status write and the event commit together. Metadata is public on-chain references only (tx hash, escrow id, contract id, amount, order type).

Behaviour change in payments, needed for a truthful from-state. The status writes are now conditional on the observed state (UPDATE ... WHERE status = 'escrowed'). Previously a racing second fund/release/refund silently overwrote the first; now it gets 409 and records nothing. If the on-chain call already succeeded for the losing request, the ledger is ahead of the database. That gap already existed for crashes at the same point; reconciling it is #24's scope (fundPaymentIntent check-then-act).

GET /admin/audit-events (admin only):

• Filters: entityType, entityId, actorUserId, from/to.
• limit is 1–200 (default 50), so there's no unbounded dump. Unknown parameters return 400.
• Ordering is (createdAt DESC, id DESC) with an opaque keyset cursor on that pair, returned as { items, nextCursor }. No existing pagination pattern was in the repo to reuse.

Docs

• ARCHITECTURE.md §3 (audit module, and the rule for Phase 3/4) and §4.10 (model and recorded transitions)
• §6.2.4 marked "foundation resolved", with the remaining gaps listed
• ARCHITECTURE_ESSENTIALS.md known-gaps entry rewritten
• docs/api/README.md (endpoint, X-Request-Id, the payments 409)
• ROADMAP.md: Phase 8 item marked "foundation done, Phase 3/4 wiring pending", plus a changelog line

Tests

tests/integration/audit.test.mts (20, own embedded Postgres on port 5441). These run the real flows over HTTP, not the service in isolation. The escrow SDK is faked through a new test seam (setEscrowSdkForTests).

• Booking:
  • an event with the right actor, role, entity, action, states, request id and timestamp, and no email or name in it
  • a request id is minted when the inbound one is malformed
  • a 5-way race gives one appointment and one event
• Rollback coupling: a real BEFORE INSERT trigger that fails the audit write, installed in the test DB (no mocks).
  • Booking returns 500, the slot stays open, there is no appointment and no event. The retry then succeeds.
  • Doctor verification and payment fund roll back the same way.
• Verification: pending→verified→rejected recorded with the admin actor; a no-op set records nothing.
• Payments:
  • created→escrowed→released and escrowed→refunded, with tx hash in metadata and no platform secrets (sentinel values checked)
  • an on-chain failure leaves the status escrowed and records no released event
  • an invalid transition gets 409 and no event
  • a release-vs-refund race gives exactly one 200 and one 409, and exactly one terminal event matching the final status
• Append-only: update, updateMany, delete, deleteMany and TRUNCATE are all rejected by the database, and the rows are unchanged. record() with the root client is refused.
• Endpoint:
  • 401 and 403 for patient and doctor
  • entity, entity+id, actor and date-range filters
  • 7 invalid queries give 400
  • pagination over 23 events with identical createdAt: every event exactly once, in a total order, across 5 pages, with a newer event inserted mid-scan not disturbing the remaining pages; a repeat scan is deterministic
• Every booked slot still has exactly one appointment.

tests/unit/audit.test.ts (26): metadata rules (16 forbidden-key cases, nested values, long strings, NaN, too many keys), record() guards, cursor round-trip and rejection, query schema, request-id middleware.

Mutation checks:

• Moving the booking's record() into a separate transaction after the booking fails the booking and rollback tests.
• Dropping the id tie-break from the cursor fails the pagination test.

npm run typecheck        → clean
npm test                 → Test Files 7 passed (7) · Tests 56 passed (56)
npm run test:integration → Test Files 5 passed (5) · Tests 42 passed (42)   (existing booking/csrf/email/throttle suites unchanged and passing)
npm run build            → clean

These were run in Ubuntu (WSL) on Node 20 to match CI, with --hookTimeout raised locally (the existing suites' beforeAll exceeds 10s on this machine). tests/testnet-integration/payments.test.mts was updated for the new actor argument and typechecks, but was not run: it needs live testnet and funded platform identities.

Not done here (explicitly)

• Phase 3/4/5 wiring (referrals, prescriptions, lab orders, fulfillment): those modules don't exist yet, and each must call record() in its own transaction when built.
• POST /auth/login-attempts/clear still logs to console only. It's out of the issue's three flows, and the comment and docs now say so.
• The app connects as the database owner, which could disable the triggers. Enforcing append-only against the owner needs a separate least-privilege DB role, which is deployment work ([Phase 9] ADR: choose production deployment target #22).

Notes for reviewers

• Open PR feat(audit): PHI read-access logging: record who viewed which clinical record (#45) #149 also creates backend/src/modules/audit/ (for AccessLog, read-access logging, a different concern). Whichever merges second needs to fold the two into one module.
• Open PRs feat(patients): patient data export (right of access) as a complete, machine-readable bundle #155 ([Phase 8] Patient data export (right of access) as a complete, machine-readable bundle #40), feat(patients): account deletion with clinical-record retention: anonymise identity, keep the audit trail #156 ([Phase 8] Account deletion with clinical-record retention: anonymise identity, keep the audit trail #41) and feat(patients): guardian and dependent accounts: booking on behalf of a minor #157 ([Phase 8] Guardian and dependent accounts: booking on behalf of a minor #42) touch app.ts, ROADMAP.md and ARCHITECTURE.md. Expect trivial doc and line conflicts only.

🤖 Generated with Claude Code

[drips-wave]

@zainabwahab-eth Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits