Zero-Knowledge OTP Verification (v2)
Issue 128-bit single-use challenge nonces, derive SHA-256 codeProof digests, verify OTPs without transmitting raw PINs, and handle failover.
SMS Pro's v2 verification APIs guarantee that plaintext user PIN codes never touch HTTP bodies, proxy logs, or network traces. Walk through the end-to-end Challenge-Response protocol.
Zero-Knowledge OTP Flow (v2)
Explore how challengeNonce and codeProof work together across server and client.
Issue Challenge & Capture challengeNonce
Call POST /api/v2/public/otp/send. SMS Pro delivers the numeric PIN out-of-band to the subscriber's handset and returns a single-use 128-bit hex challengeNonce plus otpId.
src/services/otp-v2.ts
export interface OtpSendV2Response {otpId: string;to: string;status: string;expiresAt: string;resendAfterSeconds: number;channel: string;challengeNonce: string;proofAlgorithm: 'SHA-256';proofFormat: string;}export async function issueOtpChallenge(phoneNumber: string): Promise<OtpSendV2Response> {const res = await fetch(`${process.env.SMSPRO_BASE_URL}/api/v2/public/otp/send`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Api-Key': process.env.SMSPRO_API_KEY!, }, body: JSON.stringify({ phoneNumber, senderId: 'AUTH', }),});if (!res.ok) throw new Error(`OTP send failed: ${res.status}`);const json = (await res.json()) as { data: OtpSendV2Response };return json.data;}Derive Canonical SHA-256 codeProof
Normalize both challengeNonce and the user-entered PIN with .trim().toLowerCase(), join with :, and compute the 64-character lowercase hexadecimal SHA-256 digest.
src/lib/zk-proof.ts
import { createHash } from 'node:crypto';/*** Computes Zero-Knowledge codeProof for v2 OTP and MFA verification:* canonical = challengeNonce.trim().toLowerCase() + ":" + userCode.trim().toLowerCase()* codeProof = hex(sha256(canonical))*/export function computeCodeProof(challengeNonce: string, userCode: string): string {if (!challengeNonce.trim() || !userCode.trim()) { throw new Error('challengeNonce and userCode must be non-empty');}const canonical = `${challengeNonce.trim().toLowerCase()}:${userCode.trim().toLowerCase()}`;return createHash('sha256').update(canonical, 'utf8').digest('hex');}// Browser Web Crypto equivalent (zero dependencies):export async function computeCodeProofBrowser(challengeNonce: string,userCode: string,): Promise<string> {const canonical = `${challengeNonce.trim().toLowerCase()}:${userCode.trim().toLowerCase()}`;const data = new TextEncoder().encode(canonical);const digest = await crypto.subtle.digest('SHA-256', data);return Array.from(new Uint8Array(digest)) .map((byte) => byte.toString(16).padStart(2, '0')) .join('');}Verify Proof Without Sending Plaintext PIN
Submit phoneNumber, otpId, and codeProof to POST /api/v2/public/otp/verify. The proof is checked once and cannot be reused.
src/services/otp-v2.ts
import { computeCodeProof } from '../lib/zk-proof';export interface OtpVerifyV2Response {valid: boolean;status: 'APPROVED' | 'INVALID_CODE' | 'MAX_ATTEMPTS_EXCEEDED' | 'EXPIRED' | 'NOT_FOUND';message: string;channelDelivered: 'WHATSAPP' | 'SMS' | 'SMS_FAILOVER';verifiedAt?: string;attemptsRemaining: number | null;}export async function verifyOtpProof(params: {phoneNumber: string;otpId: string;challengeNonce: string;userEnteredCode: string;}): Promise<OtpVerifyV2Response> {const codeProof = computeCodeProof(params.challengeNonce, params.userEnteredCode);const res = await fetch(`${process.env.SMSPRO_BASE_URL}/api/v2/public/otp/verify`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Api-Key': process.env.SMSPRO_API_KEY!, }, body: JSON.stringify({ phoneNumber: params.phoneNumber, otpId: params.otpId, codeProof, }),});const json = (await res.json()) as { data: OtpVerifyV2Response };return json.data;}Trigger Automatic SMS Failover
If the initial WhatsApp challenge goes undelivered or the user requests an alternate channel, invoke POST /api/v2/public/otp/failover to fall back to carrier SMS (SMS_FAILOVER) while preserving the challenge flow.
src/services/otp-v2.ts
export async function triggerOtpSmsFailover(otpId: string, phoneNumber: string) {const res = await fetch(`${process.env.SMSPRO_BASE_URL}/api/v2/public/otp/failover`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Api-Key': process.env.SMSPRO_API_KEY!, }, body: JSON.stringify({ otpId, phoneNumber, }),});if (!res.ok) { throw new Error(`OTP failover failed with status ${res.status}`);}return res.json();}