Node.js SMS Verification Code: Generating and Sending One-Time Passwords via API Integration

Generating and sending one-time passwords (OTPs) via SMS using Node.js involves creating a cryptographically secure OTP locally, sending it through an SMS API integration, and persisting an idempotent attempt record to avoid ambiguity in login processes. The OTP must be generated with a secure source, stored only as a hashed digest with an expiration time and attempt counter, and accepted exactly once.

The send operation must be idempotent to prevent issues such as creating two valid-looking texts on retry, confusing users, and incurring unnecessary delivery charges.

The integration boundary is crucial in securing the process. An OTP endpoint should be small, with a failure surface that is well-managed. A timeout does not indicate whether the message was accepted, and blindly retrying can lead to sending duplicate texts, user confusion, and additional charges. Instead, a success response should only be returned after the provider has accepted the request. Before this acceptance, the application should return a failure status.

To manage this process effectively, the application should maintain an attempt record that includes a random challenge, a normalized destination, an expiry time, delivery status, and the number of verification failures. This record allows a client-supplied request key to replay the same result for duplicate requests. The provider adapter, responsible for calling the SMS API, should be separated from the account service, which decides whether another send is permissible.

For a marketplace scenario, this boundary also protects a common workflow: a buyer signs in using an OTP, then requests a report of orders or seller activity. The report should be generated separately from the OTP request, ensuring that authentication establishes a session while a queue handles the creation and emailing of the report. Mixing these paths can lead to slow report generation being mistaken for an authentication failure.

The provided TypeScript example demonstrates a small implementation that keeps the provider generic, using `SmsGateway` to wrap an HTTP client for any service that accepts a destination and message. It defines an `OtpAttempt` interface to manage the state of each OTP attempt, including fields for the OTP ID, request ID, destination, hashed digest, expiry time, verification attempts, status, and provider message ID (if applicable).

The `digest` function hashes the OTP code using SHA-256 to ensure security, and the `sameDigest` function compares two digests securely using timing-safe equality. The `issueOtp` function generates a random OTP, creates an attempt record, and attempts to send the OTP through the provided `SmsGateway`. It checks for existing attempts to ensure idempotency and returns the attempt ID and status if an existing attempt is found.

If not, it generates a new OTP, records the attempt, and sends it using the SMS gateway. The example highlights the importance of managing the OTP lifecycle carefully to maintain security and avoid common pitfalls in SMS verification processes.