anavpdel/sms-verification-processor repository overview

This documentation provides a comprehensive overview of the SMS Verification Processor, a high-performance middleware designed to route and secure SMS-based data flows.

⁠📱 SMS Verification Processor

The SMS Verification Processor is a Kafka-driven microservice responsible for securely processing incoming SMS messages and forwarding them to service-specific APIs based on detected keywords. It ensures message integrity and authenticity through HMAC-SHA512 Authorization headers.

⁠Key Features

• Kafka Consumer: Real-time processing of incoming SMS streams.
• Keyword Routing: Intelligent message redirection based on the SMS prefix.
• HMAC-SHA512 Security: Enterprise-grade authentication for all downstream HTTP requests.
• Resilience: Centralized error handling via dedicated Kafka error topics.
• Dynamic Config: Easily scalable via environment variables for new services and keywords.

⁠Message Flow

1. Consume: Retrieve the raw SMS message from the Kafka topic.
2. Parse: Extract the <KEYWORD> and <ENCRYPTED_PAYLOAD>.
3. Resolve: Map the keyword to the destination service URL and credentials.
4. Sign: Generate a secure HMAC-SHA512 authorization header.
5. Forward: POST the structured JSON payload to the service API.
6. Audit: On failure, publish the error and original payload to the Kafka error topic.

⁠📊 Data Structures

⁠Incoming SMS Format

Messages arrive in Kafka with the following structure:

Raw SMS Body:

SERVICE1 zkwaA2SDGRUxVuERKJiG/qmpzTbcHNENEBD3RGTS9cU=

Kafka JSON Object:

JSON

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

⁠Forwarded HTTP Payload

The processor strips the keyword and forwards the following to the downstream API:

JSON

{
  "mobileNumber": "09171234567",
  "keyword": "SERVICE1",
  "message": "zkwaA2SDGRUxVuERKJiG/qmpzTbcHNENEBD3RGTS9cU=",
  "traceId": "169878025"
}

⁠🔐 Security & HMAC Specification

⁠Authorization Header

The service uses a custom HMAC scheme:

Authorization: HmacSHA512 ::

⁠Digest Generation

To validate a request, the digest must be calculated using the following logic:

1. String Construction: Concatenate using a space ( ) as a delimiter.

   " " + apiKey + " " + nonce + " " + payloadJson + " "

2. Hashing:

   $$digest = Base64(HMAC_SHA512(digestString, apiSecret))$$

⁠Implementation Example (Node.js)

JavaScript

import axios from "axios";
import { createHmac } from "crypto";

const getDigest = (apiKey, apiSecret, nonce, payload) => {
  const delimiter = " ";
  const digestString = `${delimiter}${apiKey}${delimiter}${nonce}${delimiter}${payload}${delimiter}`;

  return createHmac("sha512", apiSecret)
    .update(digestString)
    .digest("base64");
};

const getAuthorizationHeader = (apiKey, apiSecret, payload) => {
  const nonce = Date.now().toString();
  const digest = getDigest(apiKey, apiSecret, nonce, JSON.stringify(payload));
  return `HmacSHA512 ${apiKey}:${nonce}:${digest}`;
};

⁠🛠 Configuration & Deployment

⁠Environment Variables

⁠Docker Deployment

Deploy the processor using the following command:

Bash

docker run --network=prod_network \
  -e KAFKA_BROKERS=kafka:9092 \
  -e KAFKA_CONSUME_TOPIC=sms-inbound \
  -e KAFKA_ERROR_TOPIC=sms-error-log \
  -e SERVICE1_API_URL=http://api.service.com/v1/verify \
  -e SERVICE1_API_KEY=your-api-key \
  -e SERVICE1_API_SECRET=your-api-secret \
  sms-verification-processor:latest

⁠⚠️ Error Handling

If a message cannot be processed, it is routed to the KAFKA_ERROR_TOPIC with one of the following schemas:

• Unsupported Keyword: Occurs when the prefix does not match any environment variables.
• HTTP Failure: Occurs when the downstream API returns a non-2xx status code.