ALTCHA Server Demo for Java

This repository demonstrates the implementation of an ALTCHA server with spam filtering using the Java version of the altcha-lib-java library. The server provides endpoints for fetching challenges and submitting form data, including verification of Proof-of-Work (PoW) solutions and spam filtering.

Documentation

• Server Integration
• Spam Filter Payload Verification

Requirements

• Java (JDK 11 or later)
• Maven (v3.6 or later)

Installation

1. Clone the repository:

   git clone https://github.com/altcha-org/altcha-starter-java.git
   cd altcha-starter-java

2. Install dependencies:

   mvn clean install

Configuration

The server requires the following environment variables for configuration:

• ALTCHA_HMAC_KEY: Secret key used for HMAC in ALTCHA challenge generation (optional, generated if not provided).

You can create a .env file in the root directory to set these environment variables:

PORT=3000
ALTCHA_HMAC_KEY=your_custom_hmac_key

Alternatively, you can set environment variables directly in your system or IDE.

Modes of Operation

• Self-Hosted: In fully self-hosted mode, configure your ALTCHA_HMAC_KEY (a secure randomly generated key) and utilize the GET /altcha as the challengeurl and the POST /submit endpoint as the form's action.
• ALTCHA API without Spam Filter: Configure ALTCHA's API URL as challengeurl and the POST /submit endpoint as the form's action. Configure your API Key's secret as ALTCHA_HMAC_KEY (e.g., ALTCHA_HMAC_KEY=csec_...).
• ALTCHA API with Spam Filter: Configure ALTCHA's API URL as challengeurl and the POST /submit_spam_filter endpoint as the form's action. Configure your API Key's secret as ALTCHA_HMAC_KEY (e.g., ALTCHA_HMAC_KEY=csec_...).

Verification Methods

• verifySolution: Used when verifying a simple Proof-of-Work (PoW) challenge. This is the standard verification method when the Spam Filter is NOT enabled on the ALTCHA widget.

• verifyServerSignature: Used when the Spam Filter is enabled on the ALTCHA widget. When the Spam Filter is active, the format of the ALTCHA payload changes, and additional verification steps are required to ensure the submission is not spam.

Usage

To start the server, run:

mvn spring-boot:run

The server will be running on the port specified in the configuration (default is 3000).

Endpoints

GET /altcha

Fetches a new random challenge to be used by the ALTCHA widget.

• URL: /altcha
• Method: GET
• Response: JSON object containing the challenge.

Example

curl http://localhost:3000/altcha

POST /submit

Submits form data and verifies the simple PoW challenge without the spam filter.

• URL: /submit
• Method: POST
• Request Body: JSON object containing form data with the altcha field.

Example

curl -X POST -H "Content-Type: application/json" -d '{"altcha":"your_verification_payload"}' http://localhost:3000/submit

POST /submit_spam_filter

Submits form data and verifies the server signature generated by the spam filter.

• URL: /submit_spam_filter
• Method: POST
• Request Body: JSON object containing form data with the altcha field.

Example

curl -X POST -H "Content-Type: application/json" -d '{"altcha":"your_verification_payload"}' http://localhost:3000/submit_spam_filter

License

MIT