Feature: Add Auth Token and Session Persistence Models

[3m1n3nc3]

Description

Persist email verification, password reset, refresh sessions, and login attempts securely.

File Location

learnault-api/prisma/schema.prisma, migration, and learnault-api/src/domain/auth/

Design Reference

API Roadmap Phase 1: Add Auth Token and Session Persistence Models.

Dependencies

• Status: Blocked
• Blocked by: Feature: Introduce Typed Status Enums and Transition Guards #65 (Introduce Typed Status Enums and Transition Guards) — done; Feature: Add Auditable Data Lifecycle and Archive Policy #124 (Add Auditable Data Lifecycle and Archive Policy)
• Blocks: Feature: Implement Email Verification and Resend API #77 (Implement Email Verification and Resend API) — done; Feature: Implement Password Recovery and Reset API #78 (Implement Password Recovery and Reset API) — done; Feature: Implement Refresh Rotation and Logout API #130 (Implement Refresh Rotation and Logout API); Feature: Expose Session and Device Management API #131 (Expose Session and Device Management API)

Tasks

• Add hashed verification/reset token records with purpose, expiry, use, and revocation
• Add refresh session with token family, device metadata, expiry, last use, and revocation
• Add safe login-attempt records
• Add lookup/cleanup indexes and retention rules
• Generate cryptographically random raw tokens returned only once
• Test hashing, expiry, uniqueness, cleanup, and migration

Acceptance Criteria

• Only token hashes are persisted
• Purpose, expiry, one-time use, and revocation are enforceable
• Sessions are queryable without exposing tokens
• Indexes support lookup/cleanup
• Tests pass

Verification Evidence

• Attach schema/migration and token hashing/expiry tests

Difficulty

Advanced

[DiegoMoron0102]

Hi, I'd like to take this on. I've worked with Prisma schema design and auth token persistence before, so the security constraints here are familiar: storing only hashed tokens, enforcing one-time use, handling expiry and revocation.

My approach would be to add the token and session models in schema.prisma with proper indexes for lookup and cleanup, generate tokens with crypto.randomBytes and persist only their SHA-256 hashes, and build the domain logic around purpose-scoped expiry and revocation. I'll follow the patterns already established by #65 for typed enums and make sure retention aligns with #124. Since this blocks #130 and #131, I'll keep the session model flexible enough for refresh rotation and device management downstream.

I'll include migration, hashing/expiry tests, and uniqueness/cleanup coverage as the acceptance criteria require. Let me know if you'd like to assign it.

[grantfox-oss]

🦊 GrantFox — @DiegoMoron0102 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 #129)
2. Your PR will be reviewed by the learnault maintainers

Good luck! Track your progress on GrantFox.