Proof of Work (PoW) Based IAM System

📋 About the Project

This project is an Identity and Access Management (IAM) system protected against DDoS attacks using the Proof of Work mechanism. Clients must solve a cryptographic puzzle before logging into the server.

🎯 Key Features

• Proof of Work Protection: SHA-256 based difficulty adjustment
• JWT Validation: Secure token management
• Browser-Based Interface: Easy testing with web UI
• Dynamic Difficulty Levels: Adjustable difficulty per request
• Challenge Validity: Timeout control (5 minutes)

🏗️ Project Architecture

Backend Technologies

• Framework: Spring Boot 4.0.0
• Java: JDK 21
• Token: JJWT 0.11.5
• Build Tool: Maven

Directory Structure

src/
├── main/
│   ├── java/org/ybarlas/pow/
│   │   ├── PowApplication.java           # Spring Boot main class
│   │   ├── controller/
│   │   │   └── IamController.java        # API endpoints
│   │   ├── model/
│   │   │   ├── Challenge.java            # Challenge record
│   │   │   ├── ChallengeResponse.java    # Challenge response
│   │   │   ├── LoginRequest.java         # Login request
│   │   │   └── LoginResponse.java        # Login response
│   │   ├── service/
│   │   │   └── ProofOfWorkService.java   # PoW logic
│   │   └── util/
│   │       └── JWTUtils.java             # JWT operations
│   └── resources/
│       ├── application.properties        # Configuration
│       └── static/
│           └── index.html                # Web UI
└── test/
    └── java/org/ybarlas/pow/
        ├── controller/
        │   └── IamControllerIntegrationTest.java
        └── service/
            └── ProofOfWorkServiceTest.java

🔐 Proof of Work Mechanism

How It Works

1. Challenge Generation (/api/iam/challenge)

   • Server creates a JWT containing random data and difficulty level
   • Default difficulty: 4 (hash starting with 4 zeros)
   • Validity period: 5 minutes

2. PoW Solving (Client side)

   • Client computes SHA-256 hash of data + nonce
   • Increments nonce until difficulty level is reached
   • Stops when hash with first n characters as zeros is found

3. PoW Verification (/api/iam/login)

   • Server validates the JWT
   • Recalculates hash with nonce and verifies difficulty level
   • Proceeds to user authentication if successful

Difficulty Levels

Difficulty	Average Nonce	Computation
1	~16	Very easy
2	~256	Easy
3	~4,096	Medium
4	~65,536	Hard
5	~1,048,576	Very hard

🚀 Usage

Requirements

• Java 21+
• Maven 3.6+

Installation and Startup

# Clone the repository
git clone https://github.com/yunusbarlas/pow-example.git
cd pow

# Compile with Maven
mvn clean install

# Start the application
mvn spring-boot:run

The application will run at http://localhost:8090.

API Endpoints

1. Get Challenge

GET /api/iam/challenge

Response:
{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "challenge": "randomBase64String",
  "difficulty": 4
}

2. Login

POST /api/iam/login
Content-Type: application/json

{
  "username": "demo",
  "password": "password123",
  "challenge": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "nonce": 1234567
}

Response (Successful):
{
  "success": true,
  "message": "Login successful",
  "token": "token_12345678-1234-1234-1234-123456789012"
}

Response (Failed):
{
  "success": false,
  "message": "Invalid proof of work",
  "token": null
}

🧪 Test Credentials

Default demo account:

• Username: demo
• Password: password123

📱 Web Interface

Visit http://localhost:8090 to perform the following operations:

1. Get challenge from server
2. Solve PoW on client side
3. Login with the solution
4. Receive token on successful authentication

🧪 Tests

Running Tests

mvn test

📚 Resources

• Spring Boot Documentation
• JJWT Documentation
• Proof of Work Wikipedia

⚙️ Generated Content Notice

This README.md file, style in the index.html, and the following test classes were generated using AI:

• IamControllerIntegrationTest.java
• ProofOfWorkServiceTest.java

The rest of the codebase and core logic were manually implemented.

👤 Author

Yunus Barlas

---

Last Updated: November 2025