Speedro Authentication Service

A secure, scalable authentication and user management API built with Spring Boot.

Features

• User Registration with email verification
• Secure Authentication using Argon2id password hashing
• Role-based Access Control (Admin, Moderator, Developer, Seller, User)
• Email Notifications for verification codes
• Pagination & Sorting for user listing
• Async Operations for improved performance
• Input Validation with detailed error messages
• Database Integration with PostgreSQL (H2 for development)

Tech Stack

• Backend: Spring Boot 3.2.2, Java 21
• Security: Spring Security with Argon2id (Password4j)
• Database: PostgreSQL / H2 (JPA/Hibernate)
• Email: Spring Mail
• Build Tool: Gradle
• Utilities: Lombok, Jackson, Jakarta Validation

Quick Start

Prerequisites

• Java 21 or higher
• Gradle 8.x
• PostgreSQL (optional, H2 included for dev)

Installation

1. Clone the repository:

git clone https://github.com/yourusername/speedro-auth.git
cd speedro-auth

2. Configure database in src/main/resources/application.properties:

# For H2 (development)
spring.datasource.url=jdbc:h2:mem:speedrodb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

# For PostgreSQL (production)
# spring.datasource.url=jdbc:postgresql://localhost:5432/speedro
# spring.datasource.username=your_username
# spring.datasource.password=your_password

3. Configure email settings:

spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=your-email@gmail.com
spring.mail.password=your-app-password
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true

4. Build and run:

./gradlew bootRun

The API will be available at http://localhost:8080

API Overview

Authentication Endpoints

Endpoint	Method	Description
/v1/users/register	POST	Register new user
/v1/users/login	POST	Authenticate user
/v1/users/verify	POST	Verify email with code
/v1/users	GET	List all users (paginated)

Example Usage

Register a new user:

curl -X POST http://localhost:8080/v1/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "usersType": "USER_NORMAL",
    "fullName": "John Doe",
    "email": "john@example.com",
    "password": "SecurePass123"
  }'

Login:

curl -X POST http://localhost:8080/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "SecurePass123"
  }'

Verify email:

curl -X POST http://localhost:8080/v1/users/verify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "SecurePass123",
    "verificationCode": 12345
  }'

For complete API documentation, see API.md.

Project Structure

src/main/java/com/ryan/speedro/
├── SpeedroApplication.java          # Main application class
├── core/
│   ├── config/
│   │   └── security/                # Security configuration
│   │       ├── DataEncryption.java  # Base64 encoding/decoding
│   │       ├── DataHashing.java     # Password hashing (Argon2id)
│   │       └── SecurityConfiguration.java
│   └── services/
│       └── services/
│           ├── JsonResponseService.java
│           ├── MailSenderService.java
│           └── StringEscapeService.java
├── stats/                           # Statistics module (WIP)
└── users/                           # User management module
    ├── database/
    │   ├── UsersEntity.java         # User entity
    │   ├── UsersEntityRepository.java
    │   └── UsersType.java           # Role enum
    ├── login/                       # Login functionality
    ├── register/                    # Registration functionality
    ├── service/                     # Core user services
    ├── users/                       # User controller
    └── verification/                # Email verification

Security Features

• Argon2id password hashing with configurable memory, iterations, and parallelism
• Salt & Pepper for additional password security
• Input Validation using Jakarta Validation annotations
• SQL Injection Protection via JPA parameterized queries
• XSS Protection through string escaping

User Roles

Role	Description
USER_ADMIN	Full system access
USER_MODERATOR	Content moderation access
USER_DEVELOPER	API and development access
USER_SELL	Seller/merchant access
USER_NORMAL	Standard user access

Configuration

Application Properties

Key configuration options in application.properties:

# Server
server.port=8080

# Database
spring.datasource.url=jdbc:h2:mem:speedrodb
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

# Email
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=your-email@gmail.com
spring.mail.password=your-password

# Security hashing parameters
hash.salt=speedro_user
hash.pepper=@#*

Development

Running Tests

./gradlew test

Building

./gradlew build

Development Mode

./gradlew bootRun --args='--spring.profiles.active=dev'

Error Codes

The API returns structured error messages:

Error Code	Description
d[email]e[msg:blank]	Email is required
d[email]e[invalid]	Invalid email format
d[password]e[msg:char_limit]	Password must be 8-100 characters
e[msg:taken]	Email already registered

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Roadmap

• OAuth2 integration (Google, GitHub)
• JWT token authentication
• Rate limiting
• User profile management
• Password reset functionality
• Audit logging
• Docker containerization

License

This project is licensed under the MIT License - see the LICENSE file for details.

• AI has only been used for writing the documentation.