🔑 Individual Key System API

📌 Overview

This API implements a checkpoint-based key system, where users must complete a sequence of steps (e.g., Linkvertise pages) before receiving a valid key.

Instead of generating keys instantly, the system enforces a flow:

1. User requests access
2. Receives a monetized link
3. Completes the checkpoint
4. Repeats if necessary
5. Receives a key after finishing all checkpoints

---

⚙️ Environment Variables

Configure the following environment variables:

DB_URL=your_database_url
DB_PASSWORD=your_database_password

---

🧠 Core Concept

The system is based on checkpoints:

• Each user/session has a Checkpoint
• Each checkpoint tracks progress (currentCheckpoint)
• The total required checkpoints is configurable

Once all checkpoints are completed, a Key is generated and returned.

---

⚙️ Configuration (AppConfiguration)

Main configurable values:

Number of checkpoints: public int checkpoints = 1;

Key duration (default: 24 hours): public long duration = 24 * 60 * 60 * 1000;

Checkpoint expiration: public long checkpointDuration = 60 * 60 * 1000;

Linkvertise ID: public long linkvertise_id = 0;

Anti-bypass token: public String antiBypassToken = "...";

---

🔄 Flow Explained

1. User starts the process

• A Checkpoint is created
• Progress starts at 0

---

2. Request handling (handleCheckpoint)

Main flow controller:

handleCheckpoint(UUID id, String hash, boolean completed)

---

🧩 Case 1: All checkpoints completed

Condition: currentCheckpoint >= checkpoints

• Generate a new key (UUID)
• Save the key with expiration
• Delete checkpoint
• Return the key

---

🔁 Case 2: User completed a step

Condition: completed == true

• Validate anti-bypass hash
• Increment checkpoint progress
• Redirect to next step

---

🔗 Case 3: User needs to complete step

• Generate Linkvertise URL
• Return link to user

---

🔗 Link Generation

Steps:

1. Build return URL:
   /v1/checkpoints/get-key?id=UUID&completed=true

2. Encode in Base64

3. Inject into Linkvertise template:
   https://linkvertise.com/access/{id}/{random}/dynamic?...&r={encoded_url}

---

🛡️ Anti-Bypass System

To prevent users from skipping checkpoints:

• Every "completed" request must include a valid hash
• Hash is validated using AntibypassToken

If invalid: 400 Bad Request - "invalid hash"

---

⏱️ Expiration System

Checkpoints

• Expire after a defined duration
• Prevents infinite reuse or farming

Keys

• Have a fixed lifetime (e.g., 24 hours)
• Automatically become invalid after expiration

---

🧱 Architecture

Services

• CheckpointFlowService → Main logic controller
• CheckpointService → Handles checkpoint persistence
• KeyService → Handles key storage
• AntibypassToken → Security validation

---

🔥 Flow Summary

User → Request
↓
Receives Link
↓
Completes Checkpoint
↓
Validated + Progress++
↓
Repeat until done
↓
Receives Key

---

✅ Features

• Checkpoint-based access control
• Linkvertise integration
• Anti-bypass protection
• Expiring keys
• Expiring checkpoints
• UUID-based key generation

---

🚀 Notes

• Increase checkpoints to make the flow longer
• Keep antiBypassToken secret
• Use strong validation to avoid bypass exploits