SMS Verification Processor

Overview

The SMS Verification Processor is a Kafka-based microservice designed to process incoming SMS messages from an SMS receiver server. It verifies the message and forwards it to the appropriate service API based on the keyword present in the message.

Key Features

• Kafka Consumer: Listens to messages from the SMS receiver server.
• Keyword-Based Routing: Forwards messages to the respective service API.
• HMAC Authentication: Ensures secure communication with service APIs.
• Error Handling: Publishes failures to a dedicated Kafka error topic.
• Dynamic Keyword Support: Supports multiple keywords dynamically using environment variables.

---

Message Flow

1. Message Reception: The service consumes SMS messages from Kafka.
2. Message Parsing: Extracts the keyword and encrypted payload.
3. Service Mapping: Determines the correct service API based on the keyword.
4. Verification & Forwarding: Sends the payload securely using HMAC authentication.
5. Error Handling: Any failures are logged and sent to an error topic in Kafka.

---

Message Structure

Incoming SMS Format

<keyword> <encrypted_message_only_server_understand>

JSON Representation of a Received Message

{
  "mobileNumber": "......",
  "message": "SERVICE1 zkwaA2SDGRUxVuERKJiG/qmpzTbcHNENEBD3RGTS9cU=",
  "receivedDate": "2025-01-15 16:46:21",
  "traceId": "169878025",
  "shortCode": "37888"
}

Forwarding Payload to Service API

{
  "mobileNumber": "......",
  "encryptedPayload": "zkwaA2SDGRUxVuERKJiG/qmpzTbcHNENEBD3RGTS9cU=",
  "traceId": "169878025"
}

Expected Client Handling

The receiving service should validate the encrypted payload and verify if it is associated with the sender’s mobileNumber. Upon successful validation, further processing can be performed.

---

Configuration

Required Environment Variables

Environment variables should be set dynamically based on the keyword. The format follows:

<KEYWORD>_API_URL=<service_api_url>
<KEYWORD>_API_KEY=<service_api_key>
<KEYWORD>_API_SECRET=<service_api_secret>

Example:

KAFKA_BROKERS=kafka:9092
KAFKA_CONSUMER_GROUP=my-consumer-group
KAFKA_CONSUME_TOPIC=sms-new-topic
KAFKA_ERROR_TOPIC=sms-error-handler

ENABLE_SSL=false
SSL_CA_PATH=/path/to/ca.pem
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem

ENABLE_HTTP_NOTIFICATION=true

SERVICE1_API_URL=http://localhost:3000/sms
SERVICE1_API_KEY=service1-api-key
SERVICE1_API_SECRET=service1-api-secret

SERVICE2_API_URL=http://localhost:3001/sms
SERVICE2_API_KEY=service2-api-key
SERVICE2_API_SECRET=service2-api-secret

---

Deployment

Running via Docker

You can run the service using Docker with the required environment variables:

docker run --network=your_network \
  -e KAFKA_BROKERS=kafka:9092 \
  -e KAFKA_CONSUMER_GROUP=my-consumer-group \
  -e KAFKA_CONSUME_TOPIC=sms-new-topic \
  -e KAFKA_ERROR_TOPIC=sms-error-handler \
  -e ENABLE_SSL=false \
  -e ENABLE_HTTP_NOTIFICATION=true \
  -e SERVICE1_API_URL=http://localhost:3000/sms \
  -e SERVICE1_API_KEY=service1-api-key \
  -e SERVICE1_API_SECRET=service1-api-secret \
  -e SERVICE2_API_URL=http://localhost:3001/sms \
  -e SERVICE2_API_KEY=service2-api-key \
  -e SERVICE2_API_SECRET=service2-api-secret \
  sms-verification-processor

Alternatively, use an .env file:

docker run --network=your_network --env-file .env sms-verification-processor

---

Error Handling

If any issue occurs during processing, the error details are sent to the Kafka error topic (KAFKA_ERROR_TOPIC).

Example error message:

{
  "error": "Unsupported keyword: UNKNOWN_KEYWORD",
  "originalMessage": "UNKNOWN_KEYWORD encrypted_data_here",
  "timestamp": "2025-01-15T16:46:21Z"
}

---

Contributing

1. Fork the repository.
2. Create a new branch (feature/your-feature).
3. Commit your changes.
4. Push to your branch.
5. Submit a Pull Request.

---

License

This project is licensed under the MIT License.