April 10, 2025

CRUD-Test — API de Usuarios con Autenticación JWT

REST API for users with two-phase registration, stateless JWT authentication, PENDING → ACTIVE state transition via one-time token and integration tests.

Java
Spring
MySQL
Flyway
JWT
Spring AI

GitHub ↗ DeepWiki ↗

Problem

User registration in many APIs is binary: either the user exists and is active, or they don't exist. This project explores a more realistic flow where the user can remain in PENDING state after initial registration, with a short-lived partial token to complete the onboarding process.

Solution

API with two registration phases controlled by state (PENDING → ACTIVE) and differentiated JWT tokens. A partial token (15 min, single use) covers the activation flow; the full token enables all operations. Spring Security validates the token type on each endpoint.

Architecture

Single-use partial token — stored in the database, invalidated when consumed or expired; prevents replay attacks in the activation flow
MapStruct — type-safe mapping between DTOs and entities without manual reflection
Flyway — versioned migrations for the MySQL schema
Spring AI — module prepared for OpenAI integration; architecture ready to add AI assistance without refactoring
OpenAPI / Swagger UI — auto-generated documentation for all endpoints
Integration tests — coverage of the partial token repository with a dedicated database profile for testing

CRUD-Test · API Usuarios con JWT

Java 21 · Spring Boot · MySQL · Flyway · JWT · Spring AI

▶ Pruébalo — arrastra nodos · click para inspeccionar

registros

cada barra = POST /register → filter → service → BD → 201

Architecture diagram of CRUD-Test — API de Usuarios con Autenticación JWT

Technical Architecture — CRUD Test

Version: 1.0
Stack: Java 21 · Spring Boot 3.4 · Spring Data JPA · MySQL · JWT
Domain: User management — registration, authentication, account activation

1. Problem Context

Modern applications require a secure and flexible registration flow:

Incomplete registration: new users complete their data in stages, not one giant form.
Email validation: they need to confirm email before activating the account.
Partial tokens: short-lived tokens for incomplete processes, not full access.
State transitions: users move from PENDING → ACTIVE in a controlled manner.
AI integration: ready for intelligent assistants.

CRUD Test solves this via:

Full and partial JWT tokens: differentiated access by registration stage.
Two-stage flow: basic registration + complete profile.
Exhaustive validations: state transitions, token expiration.
Modular architecture: independent modules (auth, user, plan, ai).

2. System Overview

┌─────────────────────────────────────┐
│         Client (Browser)            │
│         http://localhost:3000       │
└──────────────┬──────────────────────┘
               │ HTTP/CORS
               ▼
┌──────────────────────────────────────────────────┐
│           Spring Boot Application               │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │   Auth   │  │  User    │  │  Plan    │      │
│  │ Module   │  │ Module   │  │ Module   │      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
│       │             │             │             │
│       ▼             ▼             ▼             │
│  ┌─────────────────────────────────────┐       │
│  │    JPA Repositories                 │       │
│  │  (PartialTokens, User, Plan)        │       │
│  └──────────────┬──────────────────────┘       │
│                 │                              │
└─────────────────┼──────────────────────────────┘
                  │ JDBC
                  ▼
          ┌──────────────────┐
          │   MySQL (8.0+)   │
          │                  │
          │ - users          │
          │ - plans          │
          │ - partial_tokens │
          │ - auth_logs      │
          └──────────────────┘

3. Technology Stack

Layer	Technology	Justification
Runtime	Java 21	LTS support, records, pattern matching
Framework	Spring Boot 3.4	Auto-configuration, actuator, properties
Web	Spring MVC	REST controllers, Thymeleaf views
Persistence	Spring Data JPA	JDBC abstraction, derived queries
Database	MySQL 8.0+	Stable, transactions, efficient indexes
Mapping	MapStruct 1.5	Mapper generation at compile-time
Security	Spring Security + JWT	Authentication, filters, RS256/HS256 tokens
Migrations	Flyway	Schema versioning, automatic rollback
Testing	JUnit 5 + Mockito	Unit and integration tests
Lombok	Lombok	@Data, @Getter, @Setter, @Builder boilerplate
Validation	Jakarta Validation	@NotNull, @Email, @Valid in controllers
AI (future)	Spring AI	LLM abstraction, prepared but unused
Build	Maven	Multi-module, dependency management
Logs	SLF4J + Logback	Levels, file and console output

4. Modules — Responsibilities

4.1 Auth Module

Authentication, tokens, and security management.

auth/
├── controller/
│   └── AuthController.java         # POST /auth/login, JWT validation
│
├── service/
│   ├── TokenService.java           # JWT generation and validation
│   └── PartialTokenService.java    # Partial tokens (15 min, single use)
│
├── filter/
│   └── SecurityFilter.java         # Intercepts requests, validates JWT
│
└── config/
    └── SecurityConfiguration.java  # Spring Security setup, CORS

Use Cases:

POST /auth/register → UserRegistrationService
POST /auth/login → TokenService.generateToken()
POST /auth/complete-profile → PartialTokenService.validateAndConsume()

4.2 User Module

User lifecycle, status transitions, profile management.

user/
├── entity/
│   └── User.java                   # JPA entity, fields, state machine
│
├── repository/
│   └── UserRepository.java         # Queries: findByUsername, findByEmail
│
├── service/
│   ├── UserRegistrationService.java    # Register new user → PENDING
│   ├── UserStatusService.java          # Transition PENDING → ACTIVE
│   └── UserDeactivationService.java    # Deactivate ACTIVE → DEACTIVATED
│
└── dto/
    ├── UserDefaultDTO.java         # username, email, password (input)
    ├── UserProfileCompletionDTO.java  # firstName, lastName, plan
    └── UserResponseDTO.java        # Full user data (output)

Entities & State Machine:

PENDING ──(completeProfile)──→ ACTIVE
                                 │
                                 └─(deactivate)─→ DEACTIVATED

4.3 Plan Module

Subscription plans, user plan assignments.

plan/
├── entity/
│   └── Plan.java                   # JPA entity: BASIC, PROFESSIONAL, ENTERPRISE
│
├── repository/
│   └── PlanRepository.java         # findByName, findAll
│
└── service/
    └── PlanService.java            # Get plan details, calculate pricing

Plans:

Plan	Description	Price
BASIC	Free tier, limited features	$0
PROFESSIONAL	Full features, community	$10
ENTERPRISE	Custom solutions, SLA	TBD

4.4 AI Module (Prepared, Not Used)

Ready for future AI/LLM features.

ai/
├── service/
│   └── AIAssistantService.java     # Spring AI integration (placeholder)
│
└── config/
    └── AIConfiguration.java        # OpenAI, Claude, etc. configuration

5. Data Model

5.1 Entity Diagram

┌────────────────────┐
│ User               │
├────────────────────┤
│ id (PK)            │
│ username (UNIQUE)  │
│ email (UNIQUE)     │
│ password           │
│ firstName          │
│ lastName           │
│ status             │◄─────────┐
│ plan_id (FK)       │          │
│ createdAt          │          │
│ completedAt        │          │
│ updatedAt          │          │
└────────────────────┘          │
                                │
                       ┌────────────────────┐
                       │ Plan               │
                       ├────────────────────┤
                       │ id (PK)            │
                       │ name (UNIQUE)      │
                       │ description        │
                       │ price              │
                       └────────────────────┘

┌────────────────────────┐
│ PartialTokens         │
├────────────────────────┤
│ id (PK)                │
│ user_id (FK)           │◄──────────┐
│ token (UNIQUE, SHA256) │           │
│ expiresAt              │           │
│ used (boolean)         │           │
│ createdAt              │           │
└────────────────────────┘           │
                                     │
                          ┌──────────────────┐
                          │ User (1..*)      │
                          └──────────────────┘

┌────────────────────────┐
│ AuditLog              │
├────────────────────────┤
│ id (PK)                │
│ action                 │
│ userId (nullable)      │
│ details                │
│ ipAddress              │
│ timestamp              │
└────────────────────────┘

5.2 State Transitions

Registration Flow:

┌──────────┐
│ Register │
│ (POST)   │
└────┬─────┘
     │ username, email, password
     ▼
┌───────────────────┐      ┌──────────────────┐
│ Create User       │      │ PartialToken     │
│ status=PENDING    │──────│ (15 min, 1 use)  │
│ hash password     │      │ for completion   │
└───────────────────┘      └────────────────┬─┘
                                            │
                                  ┌─────────▼──────┐
                                  │ Complete       │
                                  │ Profile (POST) │
                                  └─────────┬──────┘
                                            │
                             firstName, lastName, plan
                                            │
                                            ▼
                                  ┌────────────────────┐
                                  │ Validate Token     │
                                  │ ├─ Not expired?    │
                                  │ ├─ Not used?       │
                                  │ └─ Mark as used    │
                                  └────────┬───────────┘
                                           │
                                           ▼
                                  ┌──────────────────┐
                                  │ Update User      │
                                  │ status=ACTIVE    │
                                  │ firstName, ...   │
                                  └────────┬─────────┘
                                           │
                                           ▼
                                  ┌──────────────────┐
                                  │ Return Full JWT  │
                                  │ (1 hour valid)   │
                                  └──────────────────┘

Deactivation:

┌──────────────────────┐
│ User (ACTIVE)        │
│ DELETE /users/me     │
└──────────┬───────────┘
           │
           ▼
┌────────────────────────┐
│ Validate JWT Token     │
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│ Check status = ACTIVE  │
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│ Update status=DEACTIVATED
└────────────────────────┘

6. Request-Response Flows

6.1 Registration

Request:

POST /auth/register
Content-Type: application/json

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "MySecurePass123!"
}

Response (201 Created):

{
  "id": 1,
  "username": "john_doe",
  "email": "john@example.com",
  "status": "PENDING",
  "partialToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIn0...",
  "createdAt": "2024-05-20T10:00:00"
}

6.2 Complete Profile

Request:

POST /auth/complete-profile
Content-Type: application/json
X-Partial-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "firstName": "John",
  "lastName": "Doe",
  "plan": "BASIC"
}

Response (200 OK):

{
  "id": 1,
  "username": "john_doe",
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "plan": "BASIC",
  "status": "ACTIVE",
  "completedAt": "2024-05-20T10:05:00"
}

6.3 Login

Request:

POST /auth/login
Content-Type: application/json

{
  "username": "john_doe",
  "password": "MySecurePass123!"
}

Response (200 OK):

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIn0...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

7. Design Decisions

Decision	Choice	Rationale
Token Type	JWT RS256 (full), HS256 (partial)	Stateless, scalable, asymmetric security
Partial Token Duration	15 minutes	Limits attack window, forces urgency
Single Use Tokens	Yes, with `used` flag	Prevents replay attacks
Password Hashing	BCrypt strength 12	Slow (intentional), salt auto-generated
CORS Policy	Localhost:3000 only	Prevents CSRF, secure local dev
State Machine	PENDING → ACTIVE → DEACTIVATED	Clear lifecycle, no backward transitions
Soft Deletes	Yes (`status=DEACTIVATED`)	Data retention, audit compliance
Transactions	@Transactional, REPEATABLE_READ	Atomicity, no phantom reads
Migrations	Flyway versioned	Schema evolution, rollback safety
MapStruct	Compile-time generation	No runtime reflection, type-safe mapping

8. Resilience & Error Handling

8.1 Exception Hierarchy

Exception (Java)
│
├─ RuntimeException
│  └─ DomainException (custom)
│     ├─ UserNotFoundException
│     ├─ DuplicateUsernameException
│     ├─ WeakPasswordException
│     ├─ TokenExpiredException
│     ├─ TokenAlreadyUsedException
│     ├─ InvalidCredentialsException
│     └─ InvalidStateTransitionException
│
└─ HttpClientErrorException (for API calls)
   └─ HttpServerErrorException

8.2 Error Response

{
  "code": 400,
  "message": "Invalid email format",
  "timestamp": "2024-05-20T10:00:00"
}

9. Security Layers

[1] CORS         ─ localhost:3000 only
[2] HTTPS        ─ TLS in production
[3] JWT Validation ─ RS256 signature, expiration
[4] Authz        ─ @PreAuthorize for endpoints (future RBAC)
[5] Audit        ─ All events logged to audit_logs

10. Performance Considerations

Concern	Solution
Password Hashing	BCrypt (intentionally slow)
Token Lookups	Index on username, email
Token Expiration	Flyway cleanup job, TTL indexes
JWT Signature Verify	Public key cached in memory
Database Connections	HikariCP connection pool

Document maintained alongside code — architectural decisions are reflected in application.yml, pom.xml, and service implementations.

Internal API — CRUD Test

Version: 1.0
Stack: Spring Boot 3.4 · Spring Data JPA · MapStruct

1. Use Cases / Interfaces

CRUD Test exposes 4 main use cases as services in the domain:

1.1 Initial Registration

public interface UserRegistrationUseCase {
    
    /**
     * Registers a new user in PENDING status.
     * Generates a PartialToken (15 minutes, single use).
     * 
     * @param dto UserDefaultDTO with username, email, password
     * @return UserResponseDTO with user and partial token
     * @throws DuplicateUsernameException if username exists
     * @throws WeakPasswordException if password < 8 characters
     */
    UserResponseDTO register(UserDefaultDTO dto);
}

Flow:

Client
   │
   ▼
POST /auth/register
   {
     "username": "john_doe",
     "email": "john@example.com",
     "password": "MySecurePass123!"
   }
   │
   ▼
UserRegistrationService.register()
   ├─ Validate unique username
   ├─ Validate email format
   ├─ Validate password strength (≥8 characters)
   ├─ Hash password with BCrypt
   ├─ Create User (status=PENDING)
   ├─ Generate PartialToken (15 min)
   └─ Return UserResponseDTO
   │
   ▼
201 Created
{
  "id": 1,
  "username": "john_doe",
  "email": "john@example.com",
  "status": "PENDING",
  "partialToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "createdAt": "2024-05-20T10:00:00"
}

1.2 Complete Registration (Partial Token)

public interface UserProfileCompletionUseCase {
    
    /**
     * Completes user profile and transitions to ACTIVE.
     * Validates and consumes PartialToken (single use).
     * 
     * @param userId User ID
     * @param dto UserProfileCompletionDTO with firstName, lastName, plan
     * @param partialToken Registration token (from header)
     * @return UserResponseDTO with updated user
     * @throws TokenExpiredException if token > 15 minutes
     * @throws TokenAlreadyUsedException if already consumed
     */
    UserResponseDTO completeProfile(
        Long userId,
        UserProfileCompletionDTO dto,
        String partialToken
    );
}

Flow:

Client (with partialToken from previous step)
   │
   ▼
POST /auth/complete-profile
Header: X-Partial-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Body:
{
  "firstName": "John",
  "lastName": "Doe",
  "plan": "BASIC"
}
   │
   ▼
UserProfileCompletionService.completeProfile()
   ├─ Validate and consume PartialToken
   │  ├─ Hash token
   │  ├─ Find in DB
   │  ├─ Validate not expired (< 15 min)
   │  ├─ Validate unused (used=false)
   │  └─ Mark as used (used=true)
   │
   ├─ Validate user in PENDING status
   ├─ Update firstName, lastName
   ├─ Assign plan (BASIC, PROFESSIONAL, ENTERPRISE)
   ├─ Transition to ACTIVE
   └─ Return UserResponseDTO
   │
   ▼
200 OK
{
  "id": 1,
  "username": "john_doe",
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "plan": "BASIC",
  "status": "ACTIVE",
  "createdAt": "2024-05-20T10:00:00",
  "completedAt": "2024-05-20T10:05:00"
}

1.3 Login / JWT Generation

public interface AuthenticationUseCase {
    
    /**
     * Authenticates user with username + password.
     * Generates JWT valid for 1 hour (full claims).
     * 
     * @param dto AuthenticationDTO with username and password
     * @return TokenResponseDTO with JWT
     * @throws UserNotFoundException if username doesn't exist
     * @throws InvalidCredentialsException if password doesn't match
     * @throws InactiveUserException if status != ACTIVE
     */
    TokenResponseDTO authenticate(AuthenticationDTO dto);
}

Flow:

Client
   │
   ▼
POST /auth/login
{
  "username": "john_doe",
  "password": "MySecurePass123!"
}
   │
   ▼
TokenService.generateToken()
   ├─ Find user by username
   ├─ Validate password with BCrypt.matches()
   ├─ Validate status = ACTIVE
   ├─ Create JWT:
   │  ├─ Header: { "alg": "RS256", "typ": "JWT" }
   │  ├─ Payload: {
   │  │    "sub": "1",
   │  │    "username": "john_doe",
   │  │    "email": "john@example.com",
   │  │    "iat": 1716134400,
   │  │    "exp": 1716138000
   │  │  }
   │  └─ Signature: RSA-SHA256(header.payload, privateKey)
   │
   └─ Return TokenResponseDTO
   │
   ▼
200 OK
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

1.4 User Deactivation

public interface UserDeactivationUseCase {
    
    /**
     * Deactivates an authenticated user (soft delete).
     * Transitions from ACTIVE → DEACTIVATED.
     * 
     * @param userId ID of authenticated user
     * @return UserResponseDTO with status=DEACTIVATED
     * @throws InvalidStateTransitionException if not in ACTIVE
     */
    UserResponseDTO deactivateUser(Long userId);
}

Flow:

Client (authenticated with JWT)
   │
   ▼
DELETE /users/me
Header: Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
   │
   ▼
UserStatusService.deactivate()
   ├─ Validate authenticated user
   ├─ Validate status = ACTIVE
   ├─ Transition to DEACTIVATED
   ├─ Update updatedAt
   ├─ Log: "STATUS_CHANGED: ACTIVE → DEACTIVATED"
   └─ Return UserResponseDTO
   │
   ▼
200 OK
{
  "id": 1,
  "username": "john_doe",
  "status": "DEACTIVATED",
  "updatedAt": "2024-05-20T11:00:00"
}

2. Repositories / Data Access

2.1 UserRepository — JPA Queries

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    
    /**
     * Find by unique username.
     * Index in DB: CREATE UNIQUE INDEX idx_user_username ON users(username);
     */
    Optional<User> findByUsername(String username);
    
    /**
     * Find by unique email.
     * Index in DB: CREATE UNIQUE INDEX idx_user_email ON users(email);
     */
    Optional<User> findByEmail(String email);
    
    /**
     * Check if username exists (for prior validation).
     */
    boolean existsByUsername(String username);
    
    /**
     * Count active users (for statistics).
     */
    @Query("SELECT COUNT(u) FROM User u WHERE u.status = 'ACTIVE'")
    long countActiveUsers();
    
    /**
     * List users by status (paginated).
     */
    @Query("SELECT u FROM User u WHERE u.status = ?1 ORDER BY u.createdAt DESC")
    Page<User> findByStatusPaginated(UserStatus status, Pageable pageable);
}

Recommended indexes (Flyway):

-- V1__init_users_table.sql
CREATE UNIQUE INDEX idx_user_username ON users(username);
CREATE UNIQUE INDEX idx_user_email ON users(email);
CREATE INDEX idx_user_status ON users(status);
CREATE INDEX idx_user_created_at ON users(created_at);

2.2 PartialTokenRepository

@Repository
public interface PartialTokenRepository extends JpaRepository<PartialTokens, Long> {
    
    /**
     * Find token by hash (double hash for security).
     */
    Optional<PartialTokens> findByToken(String tokenHash);
    
    /**
     * Find active tokens for a user.
     */
    @Query("SELECT pt FROM PartialTokens pt WHERE pt.user.id = ?1 AND pt.used = false")
    List<PartialTokens> findActiveTokensForUser(Long userId);
    
    /**
     * Cleanup expired tokens (batch delete).
     */
    @Modifying
    @Query("DELETE FROM PartialTokens WHERE expiresAt < CURRENT_TIMESTAMP")
    int deleteExpiredTokens();
}

2.3 AuditLogRepository

@Repository
public interface AuditLogRepository extends JpaRepository<AuditLog, Long> {
    
    /**
     * List events for a user.
     */
    @Query("SELECT al FROM AuditLog al WHERE al.userId = ?1 ORDER BY al.timestamp DESC")
    Page<AuditLog> findByUserId(Long userId, Pageable pageable);
    
    /**
     * List events by action (for monitoring).
     */
    @Query("SELECT al FROM AuditLog al WHERE al.action = ?1 ORDER BY al.timestamp DESC")
    List<AuditLog> findByAction(String action, Pageable pageable);
}

3. DTOs — Data Transfer

3.1 Request DTOs

// Initial registration
@Data
public class UserDefaultDTO {
    @NotBlank(message = "Username required")
    @Size(min = 3, max = 100)
    private String username;
    
    @NotBlank(message = "Email required")
    @Email
    private String email;
    
    @NotBlank(message = "Password required")
    @Size(min = 8)
    private String password;
}

// Complete profile
@Data
public class UserProfileCompletionDTO {
    @NotBlank(message = "First name required")
    @Size(min = 1, max = 100)
    private String firstName;
    
    @NotBlank(message = "Last name required")
    @Size(min = 1, max = 100)
    private String lastName;
    
    @NotNull(message = "Plan required")
    private PlanType plan;
}

// Login
@Data
public class AuthenticationDTO {
    @NotBlank
    private String username;
    
    @NotBlank
    private String password;
}

3.2 Response DTOs

// User
@Data
public class UserResponseDTO {
    private Long id;
    private String username;
    private String email;
    private String firstName;
    private String lastName;
    private UserStatus status;
    private PlanType plan;
    private LocalDateTime createdAt;
    private LocalDateTime completedAt;
    private LocalDateTime updatedAt;
    
    // On initial registration, includes partial token
    private String partialToken;  // null in other responses
}

// Token JWT
@Data
public class TokenResponseDTO {
    private String accessToken;
    private String tokenType = "Bearer";  // Always Bearer
    private Long expiresIn;               // Seconds
}

// Error
@Data
public class ErrorResponseDTO {
    private int code;
    private String message;
    private LocalDateTime timestamp;
}

4. Mappers — MapStruct

@Mapper(componentModel = "spring")
public interface UserMapper {
    
    /**
     * Convert User JPA → UserResponseDTO.
     * Excludes password (never send plaintext).
     */
    @Mapping(target = "partialToken", ignore = true)
    UserResponseDTO toResponseDTO(User entity);
    
    /**
     * Convert UserDefaultDTO → User JPA.
     * Password is hashed in service, not mapper.
     */
    @Mapping(target = "password", ignore = true)
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "status", constant = "PENDING")
    User toEntity(UserDefaultDTO dto);
    
    /**
     * List users.
     */
    List<UserResponseDTO> toResponseDTOList(List<User> entities);
}

Generated by MapStruct at compile-time:

// UserMapperImpl (auto-generated)
public class UserMapperImpl implements UserMapper {
    
    @Override
    public UserResponseDTO toResponseDTO(User entity) {
        if (entity == null) return null;
        UserResponseDTO dto = new UserResponseDTO();
        dto.setId(entity.getId());
        dto.setUsername(entity.getUsername());
        dto.setEmail(entity.getEmail());
        // ... more mappings
        return dto;
    }
}

5. JPA Entities

5.1 User

@Entity
@Table(name = "users")
@Data
public class User {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "username", unique = true, nullable = false, length = 100)
    private String username;
    
    @Column(name = "email", unique = true, nullable = false, length = 255)
    private String email;
    
    @Column(name = "password", nullable = false)
    private String password;  // Hashed with BCrypt
    
    @Column(name = "first_name", length = 100)
    private String firstName;
    
    @Column(name = "last_name", length = 100)
    private String lastName;
    
    @Column(name = "status", nullable = false)
    @Enumerated(EnumType.STRING)
    private UserStatus status;  // PENDING, ACTIVE, DEACTIVATED
    
    @ManyToOne(fetch = FetchType.EAGER)
    @JoinColumn(name = "plan_id", nullable = false)
    private Plan plan;
    
    @Column(name = "created_at", nullable = false, updatable = false)
    private LocalDateTime createdAt;
    
    @Column(name = "completed_at")
    private LocalDateTime completedAt;  // When transitioned to ACTIVE
    
    @Column(name = "updated_at")
    private LocalDateTime updatedAt;
    
    @PrePersist
    protected void onCreate() {
        this.createdAt = LocalDateTime.now();
        this.updatedAt = LocalDateTime.now();
    }
    
    @PreUpdate
    protected void onUpdate() {
        this.updatedAt = LocalDateTime.now();
    }
}

State Validations:

PENDING ────(completeProfile)──→ ACTIVE
                                   │
                                   └──(deactivate)──→ DEACTIVATED
                                   
Not allowed:
  ❌ PENDING → DEACTIVATED (direct)
  ❌ ACTIVE → PENDING (backward)
  ❌ DEACTIVATED → any state (irreversible)

5.2 Plan

@Entity
@Table(name = "plans")
@Data
public class Plan {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "name", unique = true, nullable = false)
    @Enumerated(EnumType.STRING)
    private PlanType name;  // BASIC, PROFESSIONAL, ENTERPRISE
    
    @Column(name = "description")
    private String description;
    
    @Column(name = "price", nullable = false)
    private BigDecimal price;
    
    @OneToMany(mappedBy = "plan", fetch = FetchType.LAZY)
    private List<User> users;
}

5.3 PartialTokens

@Entity
@Table(name = "partial_tokens")
@Data
public class PartialTokens {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @ManyToOne(fetch = FetchType.EAGER)
    @JoinColumn(name = "user_id", nullable = false)
    private User user;
    
    @Column(name = "token", nullable = false, unique = true, length = 64)
    private String token;  // SHA256 hash of JWT
    
    @Column(name = "expires_at", nullable = false)
    private LocalDateTime expiresAt;
    
    @Column(name = "used", nullable = false)
    private boolean used = false;
    
    @Column(name = "created_at", nullable = false, updatable = false)
    private LocalDateTime createdAt;
    
    @PrePersist
    protected void onCreate() {
        this.createdAt = LocalDateTime.now();
    }
}

5.4 AuditLog

@Entity
@Table(name = "audit_logs")
@Data
public class AuditLog {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "action", nullable = false)
    private String action;  // USER_REGISTERED, LOGIN_SUCCESS, etc.
    
    @Column(name = "user_id")
    private Long userId;  // Can be null for failed attempts
    
    @Column(name = "details")
    private String details;  // JSON or free text
    
    @Column(name = "ip_address")
    private String ipAddress;
    
    @Column(name = "timestamp", nullable = false)
    private LocalDateTime timestamp;
    
    @PrePersist
    protected void onCreate() {
        this.timestamp = LocalDateTime.now();
    }
}

6. State Transitions

State Machine:

PENDING
  │ completeProfile()
  ├─ firstName, lastName assigned
  ├─ plan assigned
  └─→ ACTIVE

ACTIVE
  │ deactivate()
  └─→ DEACTIVATED

DEACTIVATED
  └─→ [Terminal, no transitions]

Validation in code:

public void validateStateTransition(UserStatus from, UserStatus to) {
    
    if (from == UserStatus.PENDING && to == UserStatus.ACTIVE) {
        // OK: registration complete
        return;
    }
    
    if (from == UserStatus.ACTIVE && to == UserStatus.DEACTIVATED) {
        // OK: deactivation
        return;
    }
    
    throw new InvalidStateTransitionException(
        String.format("Cannot transition from %s to %s", from, to)
    );
}

7. Type Conventions

Type	Usage	Example
`Long`	IDs, timestamps (ms)	`user.id`
`String`	username, email, passwords	`user.username`
`enum`	finite states	`UserStatus`
`LocalDateTime`	times without timezone	`createdAt`
`BigDecimal`	money, prices	`plan.price`
`boolean`	control flags	`token.used`

8. Testing

8.1 Unit Test — Registration Service

@SpringBootTest
@DataJpaTest
class UserRegistrationServiceTest {
    
    @Autowired
    private UserRegistrationService registrationService;
    
    @Autowired
    private UserRepository userRepository;
    
    @Test
    void shouldRegisterNewUser() {
        // Arrange
        UserDefaultDTO dto = new UserDefaultDTO();
        dto.setUsername("test_user");
        dto.setEmail("test@example.com");
        dto.setPassword("SecurePass123!");
        
        // Act
        UserResponseDTO result = registrationService.register(dto);
        
        // Assert
        assertNotNull(result.getId());
        assertEquals("test_user", result.getUsername());
        assertEquals(UserStatus.PENDING, result.getStatus());
        assertNotNull(result.getPartialToken());
        
        // Verify in DB
        Optional<User> saved = userRepository.findByUsername("test_user");
        assertTrue(saved.isPresent());
        assertEquals(UserStatus.PENDING, saved.get().getStatus());
    }
    
    @Test
    void shouldThrowOnDuplicateUsername() {
        // Arrange
        UserDefaultDTO dto1 = new UserDefaultDTO("john", "john@ex.com", "Pass123!");
        registrationService.register(dto1);
        
        // Act & Assert
        UserDefaultDTO dto2 = new UserDefaultDTO("john", "other@ex.com", "Pass123!");
        assertThrows(DuplicateUsernameException.class, 
                     () -> registrationService.register(dto2));
    }
}

8.2 Integration Test — JWT Flow

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@ActiveProfiles("test")
class AuthenticationIT {
    
    @Autowired
    private TestRestTemplate restTemplate;
    
    @Autowired
    private UserRepository userRepository;
    
    @Test
    void shouldLoginAndReturnToken() {
        // Arrange: create previous user
        User user = new User();
        user.setUsername("john_doe");
        user.setEmail("john@ex.com");
        user.setPassword(passwordEncoder.encode("SecurePass123!"));
        user.setStatus(UserStatus.ACTIVE);
        userRepository.save(user);
        
        // Act: login
        AuthenticationDTO authRequest = new AuthenticationDTO("john_doe", "SecurePass123!");
        ResponseEntity<TokenResponseDTO> response = restTemplate.postForEntity(
            "/auth/login",
            authRequest,
            TokenResponseDTO.class
        );
        
        // Assert
        assertEquals(HttpStatus.OK, response.getStatusCode());
        assertNotNull(response.getBody().getAccessToken());
        assertEquals("Bearer", response.getBody().getTokenType());
    }
}

Document maintained alongside code — interfaces are in com.example.domain.usecases.*, entities in com.example.domain.entities.*, and services in com.example.application.services.*.

Security — CRUD Test

Version: 1.0
Stack: Spring Security · JWT RS256 · BCrypt · MySQL

1. Security Model

CRUD Test implements layered security to protect user authentication and data:

Client (Browser)
   │
   ▼
[1] CORS ─────────────── Localhost:3000 only
   │
   ▼
[2] HTTPS ─────────────── TLS in production
   │
   ▼
[3] JWT Validation ────── RS256 signature, expiration
   │
   ▼
[4] Authorization ──────── Spring Security @PreAuthorize
   │
   ▼
[5] Auditing ──────────── Failed attempt logs
   │
   ▼
Resource access

2. JWT Authentication

2.1 Issuance Flow

Credentials (username, password)
   │
   ▼
┌─────────────────────────────┐
│ TokenService.generateToken()│
│ · Find user                 │
│ · Validate password BCrypt  │
│ · Create JWT payload        │
│ · Sign with private key     │
│ · Return token              │
└──────────────┬──────────────┘
               │
               ▼
┌──────────────────────┐
│ JWT Structure        │
│ Header: {           │
│   "alg": "RS256",   │
│   "typ": "JWT"      │
│ }                   │
│                     │
│ Payload: {         │
│   "sub": "1",      │
│   "username": "...",│
│   "iat": ...,      │
│   "exp": ...       │
│ }                  │
│                    │
│ Signature: <RSA>   │
└──────────────────────┘

2.2 Token Structure

Header: {
  "alg": "RS256",
  "typ": "JWT"
}

Payload: {
  "sub": "1",                           // User ID
  "username": "john_doe",
  "email": "john@example.com",
  "iat": 1716134400,                    // Issued at
  "exp": 1716138000                     // Expires (1 hour)
}

Signature: RSA-SHA256(header.payload, privateKey)

2.3 Validation on Each Request

// SecurityFilter.java
@Component
public class SecurityFilter extends OncePerRequestFilter {
    
    @Override
    protected void doFilterInternal(HttpServletRequest request, 
                                   HttpServletResponse response, 
                                   FilterChain filterChain) 
            throws ServletException, IOException {
        
        // Extract token from header
        String authHeader = request.getHeader("Authorization");
        if (authHeader != null && authHeader.startsWith("Bearer ")) {
            String token = authHeader.substring(7);
            
            // Validate signature and expiration
            try {
                Claims claims = tokenService.validateToken(token);
                String username = claims.getSubject();
                
                // Load user and permissions
                UserDetails userDetails = userService.loadUserByUsername(username);
                
                // Create authentication
                UsernamePasswordAuthenticationToken auth = 
                    new UsernamePasswordAuthenticationToken(
                        userDetails, null, userDetails.getAuthorities()
                    );
                
                SecurityContextHolder.getContext().setAuthentication(auth);
            } catch (JwtException e) {
                // Invalid or expired token
                response.sendError(HttpServletResponse.SC_UNAUTHORIZED);
                return;
            }
        }
        
        filterChain.doFilter(request, response);
    }
}

3. Password Hashing — BCrypt

3.1 Secure Storage

@Configuration
public class SecurityConfiguration {
    
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(12);  // Strength 12
    }
}

Details:

Algorithm: BCrypt (Blowfish)
Strength: 12 (rounds, default)
Duration: ~1 second per hash (intentional, slows brute-force)

Process:

Password: "MySecurePass123!"
   │
   ▼
BCryptPasswordEncoder.encode()
   │
   ├─ Generate random salt (2^12 rounds)
   ├─ Hash multiple times
   └─ Result: $2a$12$......(60 characters)
   │
   ▼
DB: password = "$2a$12$........."

Login:
   │
   ▼
User sends: "MySecurePass123!"
   │
   ▼
encoder.matches(input, hashedFromDB)
   │ Runs BCrypt on input with same salt
   │
   ▼
Match? → true/false

3.2 Registration Validations

public class UserRegistrationService {
    
    public User register(UserDefaultDTO dto) {
        
        // Validate password strength
        if (dto.getPassword().length() < 8) {
            throw new WeakPasswordException("Minimum 8 characters");
        }
        
        // Validate email
        if (!dto.getEmail().matches("^[A-Za-z0-9+_.-]+@(.+)$")) {
            throw new InvalidEmailException();
        }
        
        // Validate unique username
        if (userRepository.existsByUsername(dto.getUsername())) {
            throw new DuplicateUsernameException();
        }
        
        // Hash password
        String hashedPassword = passwordEncoder.encode(dto.getPassword());
        
        User user = new User();
        user.setUsername(dto.getUsername());
        user.setEmail(dto.getEmail());
        user.setPassword(hashedPassword);  // Never plaintext
        user.setStatus(UserStatus.PENDING);
        user.setPlan(defaultPlan);
        
        return userRepository.save(user);
    }
}

4. Partial Tokens — Special Security

4.1 Generation

public class PartialTokenService {
    
    public String generatePartialToken(User user) {
        
        // 1. Create JWT with minimal claims
        LocalDateTime expiryTime = LocalDateTime.now().plusMinutes(15);
        String jwt = Jwts.builder()
            .setSubject(user.getId().toString())
            .claim("type", "PARTIAL")
            .setIssuedAt(Date.from(Instant.now()))
            .setExpiration(Date.from(expiryTime.atZone(ZoneId.systemDefault()).toInstant()))
            .signWith(SignatureAlgorithm.HS256, secret)
            .compact();
        
        // 2. Hash the JWT before saving (never plaintext in DB)
        String tokenHash = DigestUtils.sha256Hex(jwt);
        
        // 3. Persist
        PartialTokens partial = new PartialTokens();
        partial.setUser(user);
        partial.setToken(tokenHash);
        partial.setExpiresAt(expiryTime);
        partial.setUsed(false);
        
        return jwt;  // Return to client
    }
}

4.2 Validation and Consumption

public void validateAndConsume(String tokenFromClient, Long userId) {
    
    // 1. Hash the received token
    String tokenHash = DigestUtils.sha256Hex(tokenFromClient);
    
    // 2. Find in DB
    Optional<PartialTokens> partial = repository.findByToken(tokenHash);
    if (partial.isEmpty()) {
        throw new TokenNotFoundException();
    }
    
    PartialTokens token = partial.get();
    
    // 3. Validations
    if (token.isUsed()) {
        throw new TokenAlreadyUsedException("Token already consumed");
    }
    
    if (LocalDateTime.now().isAfter(token.getExpiresAt())) {
        repository.delete(token);  // Cleanup
        throw new TokenExpiredException();
    }
    
    if (!token.getUser().getId().equals(userId)) {
        throw new UnauthorizedException("Token does not belong to user");
    }
    
    // 4. Mark as used (one time only)
    token.setUsed(true);
    repository.save(token);
    
    // 5. Log success
    auditService.log("PARTIAL_TOKEN_CONSUMED", userId);
}

Features:

Duration: 15 minutes (very short)
Single use: used flag in DB
Double hash: JWT hashed before saving in DB
Cleanup: expired tokens deleted

5. Authorization — RBAC (future)

Although all authenticated users currently have access, the architecture is ready for roles:

@Configuration
@EnableMethodSecurity(prePostEnabled = true)
public class SecurityConfiguration {
    // ...
}

@RestController
@RequestMapping("/admin")
public class AdminController {
    
    @PreAuthorize("hasRole('ADMIN')")
    @DeleteMapping("/users/{id}")
    public void deleteUser(@PathVariable Long id) {
        userService.delete(id);
    }
    
    @PreAuthorize("hasAnyRole('ADMIN', 'MODERATOR')")
    @PutMapping("/users/{id}/status")
    public void updateUserStatus(@PathVariable Long id) {
        // ...
    }
}

6. CORS — Configuration

@Configuration
public class SecurityConfiguration {
    
    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration configuration = new CorsConfiguration();
        configuration.setAllowedOrigins(Arrays.asList("http://localhost:3000"));
        configuration.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE", "OPTIONS"));
        configuration.setAllowedHeaders(Arrays.asList("*"));
        configuration.setAllowCredentials(true);
        
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", configuration);
        
        return source;
    }
}

Only allows:

Origin: http://localhost:3000
Methods: GET, POST, PUT, DELETE
Headers: All (Authorization, Content-Type, etc.)
Credentials: Yes (cookies, if any)

7. Transactions and Isolation

@Service
@Transactional  // Default, REQUIRED
public class UserStatusService {
    
    @Transactional(isolation = Isolation.REPEATABLE_READ)
    public void completeRegistration(Long userId, UserProfileCompletionDTO dto) {
        
        // Find user (implicit lock)
        User user = userRepository.findById(userId)
            .orElseThrow(UserNotFoundException::new);
        
        // Validate state
        if (user.getStatus() != UserStatus.PENDING) {
            throw new InvalidStateTransitionException();
        }
        
        // Update data
        user.setFirstName(dto.getFirstName());
        user.setLastName(dto.getLastName());
        // ...
        
        // Change state
        user.setStatus(UserStatus.ACTIVE);
        user.setUpdatedAt(LocalDateTime.now());
        
        // Transaction completes: DB updates
    }
}

ACID Guarantees:

Atomicity: all-or-nothing save
Consistency: validations before commit
Isolation: REPEATABLE_READ avoids phantom reads
Durability: DB MySQL replication

8. Auditing and Logs

@Service
public class AuditService {
    
    @Autowired
    private AuditLogRepository auditLogRepository;
    
    public void log(String action, Long userId, String details) {
        AuditLog log = new AuditLog();
        log.setAction(action);
        log.setUserId(userId);
        log.setDetails(details);
        log.setTimestamp(LocalDateTime.now());
        log.setIpAddress(getClientIp());
        
        auditLogRepository.save(log);
    }
}

Logged events:

USER_REGISTERED — new user
PARTIAL_TOKEN_GENERATED — registration token
PARTIAL_TOKEN_CONSUMED — registration completed
LOGIN_SUCCESS — successful login
LOGIN_FAILED — invalid credentials
STATUS_CHANGED — state transition
PASSWORD_CHANGED — password change

9. Input Validation

@Data
public class UserDefaultDTO {
    
    @NotBlank(message = "Username required")
    @Size(min = 3, max = 100)
    private String username;
    
    @NotBlank(message = "Email required")
    @Email(message = "Invalid email")
    private String email;
    
    @NotBlank(message = "Password required")
    @Size(min = 8, message = "Password must be at least 8 characters")
    private String password;
}

@RestController
public class UserController {
    
    @PostMapping("/register")
    public ResponseEntity<UserResponseDTO> register(
            @Valid @RequestBody UserDefaultDTO dto) {  // @Valid activates validation
        
        // If DTO is invalid, Spring returns 400 automatically
        User user = userService.register(dto);
        return ResponseEntity.status(201).body(userMapper.toResponseDTO(user));
    }
}

10. Design Decisions

10.1 BCrypt over MD5 or SHA-1

Decision: BCrypt with strength 12.
Why: Intentionally slow (resists brute-force), automatic salt, non-reversible.

10.2 Partial Tokens with Short Expiration

Decision: 15 minutes, single use.
Why: Limits attack window, forces immediate validation, prevents replay attacks.

10.3 JWT Stateless over Sessions

Decision: JWT without session persistence.
Why: Horizontally scalable, offline-validatable (with public key), stateless.

10.4 Restrictive CORS

Decision: Localhost:3000 only.
Why: Prevents CSRF, secure local development, easy production change.

10.5 Explicit Transactions

Decision: @Transactional on critical services.
Why: Guarantees atomicity, automatic rollback on error, isolation.

11. Security Checklist

Passwords hashed with BCrypt
JWT signed with RS256 (future) or HS256
Partial tokens with expiration
Input validation (@Valid)
Restrictive CORS
ACID transactions
Event auditing
Rate limiting (future)
2FA / MFA (future)
Refresh tokens (future)

Document maintained alongside code — security configurations are in application.yml and service constants.