KYC Expiration Automation: expire submissions and notify beneficiaries

[grantfox-oss]

Summary

KYCSubmission.expiresAt exists in the schema, but there is no background automation to mark submissions as expired or notify beneficiaries when their KYC validity ends. Add expiration handling in kyc.worker.ts, update KYC status automatically, and notify affected beneficiaries when KYC expires.

Background

KYC records currently carry an expiration timestamp, but the system does not act on it. Expired KYC submissions may remain VALID indefinitely, which undermines compliance and trust. Automating expiration ensures the platform enforces time-limited validation and keeps beneficiaries informed.

Scope

• Add expiration processing to the KYC worker
• Mark expired KYCSubmission records as EXPIRED or equivalent status
• Notify beneficiaries when their KYC validity ends
• Optionally notify admins or KYC reviewers of expirations
• Ensure the expiration workflow is idempotent and safe to run regularly

Goals

• Enforce KYC validity windows automatically
• Prevent stale KYC approvals from remaining active
• Create clear expiration status transitions
• Keep beneficiaries informed when they must re-submit KYC
• Add observability for expired KYC records

Functional requirements

Expiration automation

• Add a periodic job in kyc.worker.ts that:
  • scans KYCSubmission records with expiresAt <= now
  • updates status from APPROVED/VALID to EXPIRED
  • records expiration timestamp and reason
• Ensure only eligible submissions are expired:
  • typically approved/verified submissions with a defined expiresAt
  • do not expire submissions that are already rejected, pending, or already expired
• Add a configurable expiration check interval in worker settings

Notifications

• Send a notification to beneficiaries when their KYC expires
• Notification content should include:
  • KYC submission ID or profile reference
  • expiration date
  • required next steps to renew KYC
  • link to the KYC resubmission flow
• Optionally send alerts to admins or reviewers for high-risk expired cases

Status tracking

• Ensure expired KYC records are queryable via status filters
• Update any KYC dashboards or endpoints that surface submission status
• Persist audit or history entries for expiration transitions

Non-functional requirements

• Keep expiration processing lightweight and safe for repeated runs
• Use Prisma transactions if updating multiple records with side effects
• Avoid duplicate notifications for the same expiration event
• Make expiration checks configurable via environment settings
• Log expiration scan results and notification actions

Acceptance criteria

• kyc.worker.ts periodically scans for expired KYC submissions
• KYC submissions with past expiresAt are transitioned to EXPIRED
• Beneficiaries receive expiration notifications
• Already-expired or non-approved submissions are not reprocessed incorrectly
• Expired KYC submissions are visible via status-based queries
• The expiration automation is documented and configurable
• Tests cover expiration detection, status transition, and notification sending

Notes

• If there is already a KYC status enum, add EXPIRED or use the appropriate existing status
• Ensure email/websocket notification preferences are respected
• If the current worker design uses a queue or scheduler, plug expiration processing into that flow
• Document the new behavior in KYC worker and workflow docs if present

[FroDev-CR]

Hello, I'd like to apply for this project, as I'm quite qualified to handle it thanks to my training in Web 3.0 topics at The Dojo Coding and more.

This is my portfolio: Frodev.xyz

[grantfox-oss]

🦊 GrantFox — @FroDev-CR has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #91)
2. Your PR will be reviewed by the aid-linkk maintainers

Good luck! Track your progress on GrantFox.

[GBOYEE]

Hi! I'd like to work on this issue.

I have experience with this stack and can deliver a clean, tested solution. Please assign this to me and I'll submit a PR shortly.

My approach:

• Analyze the root cause
• Implement a fix following existing code patterns
• Add tests and documentation

Thanks!

[GBOYEE]

Hi! I would like to work on this issue. Please assign this to me and I will submit a PR shortly. Thanks!