Node.js SMS OTP Evidence: A 7-Step 2FA Handoff for Edtech Orders

The important trade-off in SMS OTP 2FA is not delivery speed; it is proving what happened without retaining more personal data than an edtech marketplace needs. For a seller who must approve a new order, I would keep the login service authoritative for the challenge, put the SMS integration behind a narrow adapter, and write an append-only evidence record for each state transition. A fast 200 response that cannot be reconstructed later is a failed control.

Short answer: generate a cryptographically random, short-lived code on the server; store only a keyed digest with an expiry, attempt count, purpose, and challenge identifier; send the code through a generic dispatcher; consume it atomically; and record delivery, verification, rejection, and expiry as separate events. A successful SMS request is not proof that the seller authenticated. The verification result is the security event.

My bounded production scenario is an edtech marketplace where a seller signs in from a new device just as a new course order arrives. The requirement is an API integration, but the decision axis is compliance evidence: who requested the challenge, which order workflow was waiting, when the code was accepted, and which controls prevented replay. I would set an availability SLO for the authentication path, while treating evidence completeness as a separate objective.

What should the evidence record prove?

Start with a state machine, not an SMS endpoint. A challenge has one purpose, one subject, and one bounded lifetime. Here, the purpose might be seller-login, while the order remains a reference rather than a place to copy phone numbers or codes. Useful transitions are created, dispatch_requested, dispatch_accepted, verified, rejected, expired, and locked.

The audit event should contain a challenge ID, an internal subject ID, purpose, timestamp, outcome, provider correlation ID when available, and a reason code. It should not contain the OTP, a full phone number, or an unredacted provider payload. Hashing a phone number for convenience is not automatically anonymization; an auditor can often guess small input spaces. Keep the phone-number mapping in the identity boundary, with access control and retention rules appropriate to that data.

I separate two questions that teams often collapse: did the integration accept a send request, and did the seller prove possession of the enrolled number? The former is an operational fact. The latter requires a successful server-side comparison before the challenge is consumed.

Evidence storage needs a retention policy, query path, access review, and clock discipline. Those are platform responsibilities, even when the SMS call is outsourced.

How do I implement SMS OTP-based 2FA in a Node.js API?

The public API should expose intent, not provider vocabulary. One endpoint can accept a seller session and purpose; another can accept a submitted code and challenge ID. The server resolves the enrolled destination, applies rate limits, creates the challenge, and calls a generic dispatcher. Two application operations are enough to show the boundary; a list of provider routes would only make coupling harder to see.

The challenge row needs a unique ID, a digest, an expiry, an attempt counter, a maximum-attempt policy, a consumed timestamp, and a status. Store the digest with a server-held pepper or use an HMAC construction, and compare values in constant time. A database transaction must ensure that two concurrent verification requests cannot both succeed. A fast cache can help with short-lived counters, but the evidence event and consume decision still need a durable ownership model.

The send path has its own race. I initially treated provider acceptance as a useful proxy for delivery, but that collapses two different facts and makes an audit trail misleading. Do not mark a challenge verified because a provider accepted a request, and do not create an unlimited stream of new challenges when a client retries after a timeout. Use an idempotency key at the application boundary, preserve the challenge ID across a retry, and make dispatch status explicit. A timeout means unknown outcome until the adapter can reconcile it.

That distinction matters.

The following Go example shows the security-critical comparison and consume contract behind a Node.js service. The rule belongs in the service boundary, not in an SDK callback or provider-specific template.

package otp

import (
    "crypto/subtle"
    "errors"
    "time"
)

var (
    ErrInvalidCode = errors.New("invalid code")
    ErrExpired = errors.New("challenge expired")
    ErrConsumed = errors.New("challenge already consumed")
    ErrLocked = errors.New("challenge locked")
)

func Verify(now time.Time, submitted, expected []byte, expiresAt time.Time,
    attempts, maxAttempts int, consumedAt *time.Time) error {
    if consumedAt != nil { return ErrConsumed }
    if !now.Before(expiresAt) { return ErrExpired }
    if attempts >= maxAttempts { return ErrLocked }
    if len(submitted) != len(expected) ||
        subtle.ConstantTimeCompare(submitted, expected) != 1 {
        return ErrInvalidCode
    }
    return nil
}

In the actual Node.js implementation, the transaction would lock or conditionally update the row, increment failed attempts on rejection, and set consumed_at only on success. The Go snippet is a compact contract, not a claim that a language change is required.

Where do managed services and self-hosting really differ?

The buy-versus-build decision is often framed as message price. That misses the operational surface that matters for an authentication control. A managed SMS service can reduce carrier integration work and provide delivery metadata, but it does not decide your challenge lifetime, evidence schema, redaction rules, or recovery policy. Self-hosting can give more control over the adapter and data path, while moving carrier relationships, retries, routing, abuse response, and on-call burden onto the platform team.

My capacity-planning rule is simple: count the people and failure modes, not just the API calls. If the team cannot staff carrier incidents, abuse investigations, and evidence reconciliation, self-hosting is not a free control. If a managed dependency cannot meet the authentication SLO or export evidence needed for review, it is not a complete control either.

A narrow interface keeps either choice replaceable:

package notify

import "context"

type Dispatcher interface {
    SendOTP(ctx context.Context, destination, message, idempotencyKey string) (DispatchResult, error)
}

type DispatchResult struct {
    Accepted bool
    CorrelationID string
    ProviderCode string
}

Persist a normalized result and retain a raw provider response only where the data policy allows it. That distinction makes migration a schema exercise instead of a rewrite of login logic.

Which failures should the test plan force into daylight?

A happy-path integration test proves very little. Test the boundary with a fake dispatcher, a real database transaction, and a controllable clock. The useful matrix includes duplicate idempotency keys, a provider timeout after request acceptance, an expired code, a wrong code on the final allowed attempt, two simultaneous correct submissions, a resend followed by verification of the older challenge, and a provider response containing unexpected personal data.

The critical assertions are invariants:

• one challenge can produce at most one successful verification;
• an expired or consumed challenge cannot become valid again;
• failed attempts advance even when the client receives a retryable error;
• a send retry does not silently create a second active challenge;
• no OTP appears in logs, traces, metric labels, or evidence records;
• every terminal challenge state has a timestamp and reason code.

Run load tests against the verification transaction and evidence writer, not only against the SMS mock. Capacity planning should cover a burst when a popular live class ends and many sellers process orders at once, plus queue drain after a provider interruption. Set separate SLOs for challenge API latency, dispatch acceptance, verification latency, and evidence-write durability. One aggregate number hides the failure you need to investigate. I would test the seven-step state sequence with a clock that advances across the expiry boundary, then repeat it with two workers submitting the same valid code at the same instant; the expected result is one verification event, one consumed challenge, and one rejected concurrent attempt, regardless of which worker wins the database condition.

Use counters for challenge creation, dispatch accepted, dispatch unknown, verification success, verification rejection, and lockout. Keep dimensions low-cardinality: purpose, outcome, and region may help; seller ID, phone number, challenge ID, and raw provider code do not belong in metric labels.

What changes when SMS is not enough?

SMS OTP is a possession check with known weaknesses, including number reassignment, interception, and account-recovery pressure. It can be appropriate for a constrained seller workflow, but the threat model should say what it does not defend against. A high-risk action such as changing payout details may require a stronger factor, a reauthentication window, or manual review. Do not let a successful low-assurance login silently authorize every sensitive operation.

Recovery deserves the same evidence treatment as the normal path. A support override should have an actor, a reason, an approval boundary, an expiry, and an event correlated to the seller account. “The seller could not receive a text” is a support case, not a reason to bypass the control without a record.

I would choose the architecture using a short decision record: required assurance, evidence fields, retention period, target SLO, acceptable dependency failure, on-call ownership, portability requirements, and the conditions that trigger a stronger factor. The answer may be a managed dispatcher, a self-hosted adapter, or a staged combination. The invariant is the same: the application owns authentication state and evidence, while transport remains replaceable.

For the edtech order workflow, that is the defensible handoff. A seller can be notified about a new order without turning an SMS response into an authentication claim, and a reviewer can reconstruct the decision without reading a secret that should never have been stored.

References

• https://datatracker.ietf.org/doc/html/rfc7489
• https://pages.nist.gov/800-63-4/sp800-63b.html
• https://owasp.org/www-project-authentication-cheat-sheet/
• https://owasp.org/www-project-logging-cheat-sheet/
• https://nodejs.org/api/crypto.html