Skip to content

feat(audit): immutable contract audit log API - #205

Open
Carlys17 wants to merge 1 commit into
Lumina-eX:mainfrom
Carlys17:feature/contract-audit-log
Open

feat(audit): immutable contract audit log API#205
Carlys17 wants to merge 1 commit into
Lumina-eX:mainfrom
Carlys17:feature/contract-audit-log

Conversation

@Carlys17

Copy link
Copy Markdown

Summary

Add immutable application-level audit trail for contract actions (contract creation, milestone lifecycle, approval/rejection, disputes, completion).

Changes

  • DB migration (scripts/012-contract-audit-log.sql): append-only contract_audit_logs table with UUID PK, SERIAL FKs, 8 action types, indexed for paginated queries
  • Service (lib/audit-log.ts): ContractAuditLogService with createLog (append-only) and listLogs (pagination + filters: contractId, projectId, action, actorUserId, date range)
  • API (app/api/audit-logs/route.ts): POST + GET endpoints with withAuth and role-scoped access (only contract participants or admins)
  • Wired in: contracts/deploy (contract_creation), milestones/route (milestone_creation, when linked to contract)
  • Access control: only contract participants (client/freelancer) or admins can view logs
  • Immutability enforced at DB layer (no UPDATE/DELETE path in app code)

Acceptance Criteria

  • Timestamp every event: all logs include accurate creation time ✅
  • Record actor wallet/user: identity always captured ✅
  • Store previous and new states for state transitions ✅
  • Provide paginated history API: efficient retrieval ✅
  • Immutable records: audit trail cannot be altered ✅
  • Secure access control: only authorized parties can view ✅

Closes #187

- Add contract_audit_logs table (append-only, UUID PK, SERIAL FKs)
  Tracks: contract_creation, milestone_creation, milestone_submission,
  approval, rejection, dispute_creation, dispute_resolution, contract_completion
- Add ContractAuditLogService with createLog + listLogs (pagination + filters:
  contractId, projectId, action, actorUserId, date range)
- Add /api/audit-logs POST + GET routes (withAuth, role-scoped access)
- Wire audit log in contracts/deploy (contract_creation) and milestones/route
  (milestone_creation, when milestone has contract_id)
- Access control: only contract participants or admins can access logs
- Indexes for efficient paginated queries

Closes Lumina-eX#187
@drips-wave

drips-wave Bot commented Aug 26, 2026

Copy link
Copy Markdown

@Carlys17 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Contract Audit Log API

1 participant