### Clone ALTCHA Starter Node.js Repository

Source: https://github.com/altcha-org/altcha-starter-nodejs-ts/blob/main/README.md

Clone the repository to get started with the ALTCHA server demo. Navigate into the cloned directory.

```sh
git clone https://github.com/altcha-org/altcha-starter-nodejs-ts.git
cd altcha-starter-nodejs-ts
```

--------------------------------

### Configure and Start Server

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Set environment variables and launch the development server.

```bash
# Environment configuration (.env file)
PORT=3000
ALTCHA_HMAC_KEY=your_custom_hmac_key  # For self-hosted mode
# Or use ALTCHA API secret: ALTCHA_HMAC_KEY=csec_your_api_secret

# Start the development server
npm install
npm run dev

# Server output:
# Server is running on port 3000
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/altcha-org/altcha-starter-nodejs-ts/blob/main/README.md

Install the necessary Node.js dependencies using npm.

```sh
npm install
```

--------------------------------

### Start ALTCHA Server

Source: https://github.com/altcha-org/altcha-starter-nodejs-ts/blob/main/README.md

Run the development server using npm. The server will be accessible on the configured port.

```sh
npm run dev
```

--------------------------------

### GET /altcha

Source: https://github.com/altcha-org/altcha-starter-nodejs-ts/blob/main/README.md

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

```APIDOC
## GET /altcha

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

### Method
GET

### Endpoint
/altcha

### Response
#### Success Response (200)
- **challenge** (object) - JSON object containing the challenge.
```

--------------------------------

### GET /altcha - Challenge Generation Endpoint

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Generates a new random Proof-of-Work challenge for the ALTCHA widget. The challenge includes cryptographic parameters that the client must solve before form submission is accepted. The complexity is controlled by the `maxNumber` parameter, and challenges are signed using an HMAC key for verification integrity.

```APIDOC
## GET /altcha - Challenge Generation Endpoint

### Description
Generates a new random Proof-of-Work challenge for the ALTCHA widget. The challenge includes cryptographic parameters that the client must solve before form submission is accepted. The complexity is controlled by the `maxNumber` parameter, and challenges are signed using an HMAC key for verification integrity.

### Method
GET

### Endpoint
/altcha

### Request Example
```bash
curl http://localhost:3000/altcha
```

### Response
#### Success Response (200)
- **algorithm** (string) - The hashing algorithm used for the challenge.
- **challenge** (string) - The unique challenge string.
- **salt** (string) - A random salt value for the challenge.
- **signature** (string) - An HMAC signature for the challenge integrity.

#### Response Example
```json
{
  "algorithm": "SHA-256",
  "challenge": "a1b2c3d4e5f6...",
  "salt": "random-salt-value",
  "signature": "hmac-signature..."
}
```

### Usage
Use this endpoint as the `challengeurl` in your ALTCHA widget configuration:
```html
<altcha-widget challengeurl="http://localhost:3000/altcha"></altcha-widget>
```
```

--------------------------------

### Generate ALTCHA Challenge

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Fetch a new challenge from the server to initialize the ALTCHA widget.

```bash
# Fetch a new challenge for the ALTCHA widget
curl http://localhost:3000/altcha

# Expected response:
# {
#   "algorithm": "SHA-256",
#   "challenge": "a1b2c3d4e5f6...",
#   "salt": "random-salt-value",
#   "signature": "hmac-signature..."
# }

# Use this endpoint as the challengeurl in your ALTCHA widget configuration:
# <altcha-widget challengeurl="http://localhost:3000/altcha"></altcha-widget>
```

--------------------------------

### POST /submit - Simple PoW Verification Endpoint

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Accepts form submissions and verifies the Proof-of-Work solution without spam filtering. This endpoint uses `verifySolution()` from altcha-lib to validate that the client correctly solved the challenge. Use this when you only need bot protection without content classification.

```APIDOC
## POST /submit - Simple PoW Verification Endpoint

### Description
Accepts form submissions and verifies the Proof-of-Work solution without spam filtering. This endpoint uses `verifySolution()` from altcha-lib to validate that the client correctly solved the challenge. Use this when you only need bot protection without content classification.

### Method
POST

### Endpoint
/submit

### Parameters
#### Request Body
- **altcha** (object) - Required - The ALTCHA payload containing the solution.
  - **algorithm** (string) - Required - The hashing algorithm used.
  - **challenge** (string) - Required - The challenge string.
  - **number** (integer) - Required - The solved number.
  - **salt** (string) - Required - The salt used for the challenge.
  - **signature** (string) - Required - The signature of the solution.
- **email** (string) - Optional - The user's email address.
- **message** (string) - Optional - The user's message.

### Request Example
```bash
curl -X POST http://localhost:3000/submit \
  -F 'altcha={"algorithm":"SHA-256","challenge":"...","number":12345,"salt":"...","signature":"..."}' \
  -F 'email=user@example.com' \
  -F 'message=Hello World'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the verification was successful.
- **data** (object) - Contains the submitted form data if successful.
  - **altcha** (object) - The verified ALTCHA payload.
  - **email** (string) - The submitted email.
  - **message** (string) - The submitted message.

#### Error Response
- **error** (string) - Description of the error (e.g., "Altcha payload missing", "Invalid Altcha payload").

#### Response Example (Success)
```json
{
  "success": true,
  "data": {
    "altcha": "...",
    "email": "user@example.com",
    "message": "Hello World"
  }
}
```

#### Response Example (Error)
```json
{ "error": "Altcha payload missing" }
```
```

--------------------------------

### Verify Simple ALTCHA Solution

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Verifies a basic Proof-of-Work solution without spam filter analysis. Ensure the provided solution string matches the expected format.

```typescript
import { verifySolution } from 'altcha-lib';

// Verify simple PoW solution (without spam filter)
const isValid = await verifySolution(
  '{"algorithm":"SHA-256","challenge":"...","number":12345,"salt":"...","signature":"..."}',
  'your-secret-key'
);
// Returns: boolean
```

--------------------------------

### Configure ALTCHA Server Environment Variables

Source: https://github.com/altcha-org/altcha-starter-nodejs-ts/blob/main/README.md

Set environment variables for server configuration, including the port and an optional HMAC key for challenge generation. A .env file is commonly used for this.

```ini
PORT=3000
ALTCHA_HMAC_KEY=your_custom_hmac_key
```

--------------------------------

### Submit Form with Simple PoW Verification

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Verify form submissions using the ALTCHA PoW solution without content classification.

```bash
# Submit form data with ALTCHA verification payload
curl -X POST http://localhost:3000/submit \
  -F 'altcha={"algorithm":"SHA-256","challenge":"...","number":12345,"salt":"...","signature":"..."}' \
  -F 'email=user@example.com' \
  -F 'message=Hello World'

# Success response:
# {
#   "success": true,
#   "data": {
#     "altcha": "...",
#     "email": "user@example.com",
#     "message": "Hello World"
#   }
# }

# Error response (missing payload):
# { "error": "Altcha payload missing" }

# Error response (invalid solution):
# { "error": "Invalid Altcha payload" }
```

--------------------------------

### POST /submit

Source: https://github.com/altcha-org/altcha-starter-nodejs-ts/blob/main/README.md

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

```APIDOC
## POST /submit

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

### Method
POST

### Endpoint
/submit

### Parameters
#### Request Body
- **altcha** (string) - Required - ALTCHA verification payload.

### Request Example
curl -X POST -F 'altcha=your_verification_payload' http://localhost:3000/submit
```

--------------------------------

### Generate ALTCHA Challenge

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Use to create a new Proof-of-Work challenge. Configure complexity with `maxNumber`. Requires an HMAC key for signing.

```typescript
import { createChallenge } from 'altcha-lib';

// Generate a new challenge with configurable complexity
const challenge = await createChallenge({
  hmacKey: 'your-secret-key',
  maxNumber: 50000  // Higher = harder challenge
});
// Returns: { algorithm, challenge, salt, signature }
```

--------------------------------

### Fetch ALTCHA Challenge

Source: https://github.com/altcha-org/altcha-starter-nodejs-ts/blob/main/README.md

Use this endpoint to retrieve a new random challenge for the ALTCHA widget. This is typically used in self-hosted mode.

```sh
curl http://localhost:3000/altcha
```

--------------------------------

### Submit Form Data for Simple PoW Verification

Source: https://github.com/altcha-org/altcha-starter-nodejs-ts/blob/main/README.md

Submit form data to the /submit endpoint for verification of a simple Proof-of-Work (PoW) challenge. This endpoint is used when the ALTCHA widget's Spam Filter is NOT enabled.

```sh
curl -X POST -F 'altcha=your_verification_payload' http://localhost:3000/submit
```

--------------------------------

### POST /submit_spam_filter - Spam Filter Verification Endpoint

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Handles form submissions with full spam filtering enabled. Uses `verifyServerSignature()` to validate the server-signed payload and `verifyFieldsHash()` to ensure form field values haven't been tampered with since spam classification. Submissions classified as "BAD" are automatically rejected.

```APIDOC
## POST /submit_spam_filter - Spam Filter Verification Endpoint

### Description
Handles form submissions with full spam filtering enabled. Uses `verifyServerSignature()` to validate the server-signed payload and `verifyFieldsHash()` to ensure form field values haven't been tampered with since spam classification. Submissions classified as "BAD" are automatically rejected.

### Method
POST

### Endpoint
/submit_spam_filter

### Parameters
#### Request Body
- **altcha** (string) - Required - Base64 encoded payload from the ALTCHA widget.
- **email** (string) - Optional - The user's email address.
- **message** (string) - Optional - The user's message.

### Request Example
```bash
curl -X POST http://localhost:3000/submit_spam_filter \
  -F 'altcha=base64-encoded-payload-from-widget' \
  -F 'email=user@example.com' \
  -F 'message=Legitimate message content'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the verification was successful.
- **data** (object) - Contains the submitted form data if successful.
  - **altcha** (object) - The verified ALTCHA payload.
  - **email** (string) - The submitted email.
  - **message** (string) - The submitted message.
- **verificationData** (object) - Data from the spam filter verification.
  - **classification** (string) - The spam classification (e.g., "GOOD", "BAD").
  - **fields** (array) - List of fields included in the hash.
  - **fieldsHash** (string) - SHA256 hash of the form fields.
  - **score** (number) - Spam score.

#### Error Response
- **error** (string) - Description of the error (e.g., "Classified as spam", "Invalid fields hash").

#### Response Example (Success)
```json
{
  "success": true,
  "data": {
    "altcha": "...",
    "email": "user@example.com",
    "message": "Legitimate message content"
  },
  "verificationData": {
    "classification": "GOOD",
    "fields": ["email", "message"],
    "fieldsHash": "sha256-hash-of-fields",
    "score": 0.1
  }
}
```

#### Response Example (Spam Detected)
```json
{ "error": "Classified as spam" }
```

#### Response Example (Fields Tampered)
```json
{ "error": "Invalid fields hash" }
```
```

--------------------------------

### POST /submit_spam_filter

Source: https://github.com/altcha-org/altcha-starter-nodejs-ts/blob/main/README.md

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

```APIDOC
## POST /submit_spam_filter

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

### Method
POST

### Endpoint
/submit_spam_filter

### Parameters
#### Request Body
- **altcha** (string) - Required - ALTCHA verification payload.

### Request Example
curl -X POST -F 'altcha=your_verification_payload' http://localhost:3000/submit_spam_filter
```

--------------------------------

### Verify ALTCHA Server Signature with Spam Filter

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Verifies the server signature for submissions when the spam filter is enabled. This function is part of the content-aware spam filtering process.

```typescript
import { verifyServerSignature } from 'altcha-lib';

// Verify server signature (with spam filter enabled)
const { verified, verificationData } = await verifyServerSignature(
  'base64-payload',
  'your-api-secret'
);
// Returns: { verified: boolean, verificationData: { classification, fields, fieldsHash, score } }
```

--------------------------------

### Submit Form with Spam Filter Verification

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Verify form submissions including spam classification and field integrity checks.

```bash
# Submit form with spam filter verification
curl -X POST http://localhost:3000/submit_spam_filter \
  -F 'altcha=base64-encoded-payload-from-widget' \
  -F 'email=user@example.com' \
  -F 'message=Legitimate message content'

# Success response with verification data:
# {
#   "success": true,
#   "data": {
#     "altcha": "...",
#     "email": "user@example.com",
#     "message": "Legitimate message content"
#   },
#   "verificationData": {
#     "classification": "GOOD",
#     "fields": ["email", "message"],
#     "fieldsHash": "sha256-hash-of-fields",
#     "score": 0.1
#   }
# }

# Error response (spam detected):
# { "error": "Classified as spam" }

# Error response (fields tampered):
# { "error": "Invalid fields hash" }
```

--------------------------------

### Verify ALTCHA Form Fields Hash

Source: https://context7.com/altcha-org/altcha-starter-nodejs-ts/llms.txt

Checks if form fields have been tampered with after classification. Use this in conjunction with `verifyServerSignature` to ensure data integrity.

```typescript
import { verifyFieldsHash } from 'altcha-lib';

// Verify that form fields haven't been modified since classification
const fieldsValid = await verifyFieldsHash(
  formData,           // FormData object
  ['email', 'message'], // Fields that were classified
  'expected-hash'     // Hash from verificationData
);
// Returns: boolean
```

--------------------------------

### Submit Form Data for Spam Filter Verification

Source: https://github.com/altcha-org/altcha-starter-nodejs-ts/blob/main/README.md

Submit form data to the /submit_spam_filter endpoint for verification of the server signature generated by the ALTCHA Spam Filter. This is used when the Spam Filter is enabled.

```sh
curl -X POST -F 'altcha=your_verification_payload' http://localhost:3000/submit_spam_filter
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.