Multi-currency digital savings wallet — REST API with authentication, transactions, and audit trail.

Built with Java 17, Spring Boot 3.4.2, and PostgreSQL 16.

This is a learning project built with AI assistance to explore how a savings wallet API works under the hood — authentication flows, ACID financial transactions, audit logging, and security practices. Some sections still need review and polish.

A REST API for a digital savings wallet where users can:

• Register and manage their profile
• Create savings wallets in multiple currencies (USD, EUR, COP, MXN, ARS)
• Deposit, withdraw, and transfer funds between wallets
• Track every operation through a full audit trail
• Authenticate with dual-token JWT and optional two-factor authentication

The idea came from wanting to understand the moving parts of a real savings wallet — not just the happy path, but edge cases, concurrency, token rotation, and what happens when things go wrong.

• Registration, profile updates, and soft-delete accounts
• Role-based access: USER, ADMIN, MANAGER
• Account lockout after repeated failed login attempts
• Two-Factor Authentication via TOTP (compatible with Google Authenticator, Authy)

• One wallet per user per currency
• Supported currencies: USD, EUR, COP, MXN, ARS
• Wallet states: ACTIVE, SUSPENDED, CLOSED
• Balance updates with pessimistic locking

• Configurable limits: max per transaction, max per day
• 2FA threshold: operations above a configurable amount require a TOTP code
• Pessimistic locking on balance reads to prevent race conditions
• Unique reference code per transaction

• Dual-token JWT: Access Token (short-lived) + Refresh Token (longer-lived with rotation)
• Refresh token stored as SHA-256 hash — real revocation on logout
• UUID primary keys on all entities (no sequential IDs)
• Stack traces never reach the client — all errors go through a centralized handler
• Input validation on every endpoint

• Every sensitive operation generates a log entry
• IP address, User-Agent, timestamp, and contextual details per event
• Database triggers for automatic state-change tracking

Pattern: Domain-Driven Design — code organized by business domain, not by layer type.

com.wallet.secure/
├── config/          # SecurityConfig, OpenApiConfig, AuditConfig, JwtConfig
├── auth/            # Authentication: JWT, 2FA, sessions
│   ├── controller/, dto/, entity/, repository/, security/, service/
├── user/            # Users and profiles
├── wallet/          # Wallets and balances
├── transaction/     # Transactions and history (business core)
├── audit/           # Security audit log
└── common/          # ApiResponse<T>, exceptions, enums, validators

Each domain owns its controllers, DTOs, entities, repositories, and services. Nothing lives at the root level grouped by type.

• Java 17+
• Docker and Docker Compose

git clone https://github.com/DJAngel973/Secure-Wallet-API.git
cd Secure-Wallet-API

# Copy and fill in the environment variables
cp .env.example .env

# Start PostgreSQL
docker compose up -d

# Run the application (dev profile)
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

./mvnw test                              # All unit tests (uses H2 in-memory, no DB needed)
./mvnw test -Dtest=TransactionServiceTest  # Single test class

Once running: http://localhost:8080/swagger-ui.html

All responses follow a standard wrapper:

{
  "success": true,
  "message": "Operation completed",
  "data": { }
}

Note: endpoints listed in Features above have not been tested end-to-end yet. The Swagger UI at http://localhost:8080/swagger-ui.html lists all available endpoints for exploration when the app is running.

PostgreSQL 16 with schema managed through versioned SQL scripts — Hibernate validates but never creates or modifies tables.

This project uses the OWASP Top 10 as a guide for security decisions. Here is what is currently addressed:

• Review and test all endpoints end-to-end
• Polish existing code sections marked for improvement
• Postman collection for easier API exploration

MIT © 2025–2026 DJAngel973