Auth account lifecycle: password reset, email change, deactivation & audit trail — backend EPIC

[grantfox-oss]

DESCRIPTION

apps/api/src/auth/auth.service.ts only implements login and register — there is no way for a user who forgets their password to recover their account, no way to change the email on file, and no way for an admin to deactivate a compromised or fraudulent account. This epic closes the account-lifecycle gap using Supabase Auth's existing primitives, and logs every lifecycle event the same way the rest of the platform already does via AuditService.

GOAL

Users can recover a forgotten password and change their email through a real flow; admins can deactivate/reactivate an account; every auth lifecycle event (reset requested, reset completed, email changed, deactivated, reactivated) is audit-logged; and auth endpoints are rate-limited against abuse.

REQUIREMENTS

• POST /auth/forgot-password — triggers Supabase's resetPasswordForEmail recovery flow (never reveal whether an email exists).
• POST /auth/reset-password — completes the reset using the Supabase recovery token, sets the new password.
• POST /auth/change-email (authenticated) — starts Supabase's email-change confirmation flow.
• PATCH /users/:id/deactivate and PATCH /users/:id/reactivate (admin only, mirroring the admin-only pattern already used in UsersService.setRole) — soft-disable/enable an account (block login while deactivated).
• Emit an audit event for every lifecycle action above via the existing AuditService.emit() pattern (see apps/api/src/audit/), the same way other modules already do.
• Basic rate limiting on login, forgot-password, and register to prevent credential-stuffing/abuse (reuse @nestjs/throttler if already present, or add it scoped to these endpoints only).

ACCEPTANCE CRITERIA

• Forgot/reset-password flow works end-to-end against a local Supabase instance (or mocked SupabaseService, per apps/api/src/**/*.service.spec.ts), including the "don't leak whether the email exists" behavior.
• Deactivated users cannot log in; reactivation restores access; both are admin-only and audited.
• Every new endpoint has a unit test mocking SupabaseService — no real VELAR database or credentials required.
• npm run build, npm run lint, npm run test pass in apps/api with NO VELAR credentials.
• docs/BACKEND.md updated with the new endpoints and the audit events they emit.

NOTES

Relevant files: apps/api/src/auth/auth.service.ts, apps/api/src/auth/auth.controller.ts, apps/api/src/users/users.service.ts, apps/api/src/users/users.controller.ts, apps/api/src/audit/audit.service.ts (reuse, don't reinvent), packages/types/src/ (add request/response types for the new endpoints). Do not touch supabase/migrations/ schema beyond what Supabase Auth already provides — no new tables required for this scope. EXTEND auth/users, don't rewrite existing login/register logic (docs/AGENTS.md §3).

No VELAR credentials required: verifiable locally with a mocked SupabaseService — no real database, passwords, or service_role key.

Difficulty: Advanced
Priority: High

PR REQUIREMENTS

• Ship this as a single pull request — do not split into stacked/sequential PRs.
• Your PR description must include Closes #<this-issue-number> (this issue's GitHub number) so merging auto-closes it.

CAMPAIGN REQUIREMENTS (FWC26)

To be eligible for the reward on this issue, the contributor must:

• Follow Velar on X: https://x.com/VelarApp
• Star the repository: https://github.com/Velar-Bonds/Velar
• Follow the Velar-Bonds organization on GitHub: https://github.com/Velar-Bonds

[Naajih09]

Hi, I'd like to work on this issue. I've gone through the description and acceptance criteria and I'm confident I can deliver it. I'll make sure every acceptance criterion is met and submit a clean, tested PR. Please assign it to me.

[Peculiarr7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. I’ll prioritize this immediately and ensure a reliable solution is delivered as soon as possible. Thank you!

[codebestia]

I’d like to take this one on. I’ve gone through the requirements and I think I can implement it without disturbing the existing login/register flow.

I’d keep the changes focused on extending the current auth/users services: use the existing SupabaseService primitives for password recovery and email changes, follow the existing admin authorization pattern for deactivate/reactivate, and reuse AuditService.emit() rather than introducing another logging mechanism. I’ll also make sure the forgot-password response doesn’t disclose whether an account exists.

For the security side, I’ll add throttling specifically around the relevant auth endpoints rather than broadly changing API behavior, and make sure deactivation actually prevents login while still allowing reactivation to restore access.

I’ll cover the new flows with mocked Supabase calls and tests for the important edge cases, including the non-enumerating forgot-password behavior, admin-only account state changes, and audit events. I’ll also update the backend docs and verify build, lint, and test work without any VELAR credentials.

I’m happy to take this through implementation and a single PR, including the required Closes # reference. I’d appreciate being assigned this one.

[Yerickmondra15]

Hi, I'd like to take this issue.

I just submitted the PR for #72 (extracting the design system into @velar/ui),
so I already have the monorepo set up and running build/lint/typecheck across
both workspaces.

My plan for #77:

• forgot-password / reset-password on top of Supabase's resetPasswordForEmail,
  returning an identical response whether or not the email exists, so the
  endpoint never leaks account existence
• change-email (authenticated), using Supabase's email-change confirmation flow
• deactivate / reactivate, admin-only, following the same authorization pattern
  UsersService.setRole already uses. I plan to block login via Supabase Auth's
  ban primitive rather than adding a column, so no schema changes are needed
• AuditService.emit() on every lifecycle event, with new AuditEventType entries
  in packages/types
• rate limiting scoped to login, register and forgot-password. @nestjs/throttler
  is already a dependency and login already carries @Throttle, so I'll extend
  the existing setup rather than introduce a new one

Unit test per endpoint with a mocked SupabaseService, following the existing
*.service.spec.ts pattern in apps/api. No changes to supabase/migrations, and
extending auth/users instead of rewriting the working login/register logic.

I'll update docs/BACKEND.md with the new endpoints and the audit events each
one emits.

[grantfox-oss]

🦊 GrantFox — @Yerickmondra15 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@Yerickmondra15's PR #91 was approved and merged by @josueazc.

🏆 @Yerickmondra15: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (535 total points). Track your full progress on GrantFox.

👏 Great work, @Yerickmondra15! Keep contributing to Velar-Bonds.