sms-verification-api 0.9.1

package/src/sns.js

@@ -0,0 +1,236 @@
+/**
+ * AWS SNS HTTP API Client for Cloudflare Workers
+ * @class SNSClient
+ */
+class SNSClient {
+  /**
+   * Create a new SNS client instance
+   * @param {Object} options - Configuration options
+   * @param {string} options.accessKeyId - AWS access key ID
+   * @param {string} options.secretAccessKey - AWS secret access key
+   * @param {string} [options.region='us-east-1'] - AWS region
+   */
+  constructor(options = {}) {
+    this.accessKeyId = options.accessKeyId;
+    this.secretAccessKey = options.secretAccessKey;
+    this.region = options.region || 'us-east-1';
+    this.endpoint = `https://sns.${this.region}.amazonaws.com`;
+  }
+
+  // Convert string to Uint8Array
+  stringToUint8Array(str) {
+    return new TextEncoder().encode(str);
+  }
+
+  // Convert Uint8Array to hex string
+  arrayBufferToHex(buffer) {
+    return Array.from(new Uint8Array(buffer))
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  // AWS Signature Version 4 signing using Web Crypto API
+  async sign(method, url, headers, payload) {
+    const now = new Date();
+    const amzDate = now.toISOString().replace(/[:\-]|\.\d{3}/g, '');
+    const dateStamp = amzDate.substr(0, 8);
+
+    // Create canonical request
+    const canonicalUri = '/';
+    const canonicalQuerystring = url.split('?')[1] || '';
+    
+    // Add required headers
+    headers['host'] = `sns.${this.region}.amazonaws.com`;
+    headers['x-amz-date'] = amzDate;
+    
+    // Calculate payload hash
+    const payloadHash = await crypto.subtle.digest('SHA-256', this.stringToUint8Array(payload))
+      .then(buffer => this.arrayBufferToHex(buffer));
+    headers['x-amz-content-sha256'] = payloadHash;
+
+    // Create canonical headers
+    const sortedHeaders = Object.keys(headers).sort().map(key => 
+      `${key.toLowerCase()}:${headers[key]}`
+    ).join('\n');
+    
+    const signedHeaders = Object.keys(headers).sort().map(key => 
+      key.toLowerCase()
+    ).join(';');
+
+    const canonicalRequest = [
+      method,
+      canonicalUri,
+      canonicalQuerystring,
+      sortedHeaders,
+      '',
+      signedHeaders,
+      payloadHash
+    ].join('\n');
+
+    // Create string to sign
+    const algorithm = 'AWS4-HMAC-SHA256';
+    const credentialScope = `${dateStamp}/${this.region}/sns/aws4_request`;
+    
+    const canonicalRequestHash = await crypto.subtle.digest('SHA-256', this.stringToUint8Array(canonicalRequest))
+      .then(buffer => this.arrayBufferToHex(buffer));
+    
+    const stringToSign = [
+      algorithm,
+      amzDate,
+      credentialScope,
+      canonicalRequestHash
+    ].join('\n');
+
+    // Calculate signature using Web Crypto API
+    const kDate = await crypto.subtle.importKey(
+      'raw',
+      this.stringToUint8Array(`AWS4${this.secretAccessKey}`),
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign']
+    ).then(key => crypto.subtle.sign('HMAC', key, this.stringToUint8Array(dateStamp)));
+
+    const kRegion = await crypto.subtle.importKey(
+      'raw',
+      kDate,
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign']
+    ).then(key => crypto.subtle.sign('HMAC', key, this.stringToUint8Array(this.region)));
+
+    const kService = await crypto.subtle.importKey(
+      'raw',
+      kRegion,
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign']
+    ).then(key => crypto.subtle.sign('HMAC', key, this.stringToUint8Array('sns')));
+
+    const kSigning = await crypto.subtle.importKey(
+      'raw',
+      kService,
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign']
+    ).then(key => crypto.subtle.sign('HMAC', key, this.stringToUint8Array('aws4_request')));
+
+    const signature = await crypto.subtle.importKey(
+      'raw',
+      kSigning,
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign']
+    ).then(key => crypto.subtle.sign('HMAC', key, this.stringToUint8Array(stringToSign)))
+    .then(buffer => this.arrayBufferToHex(buffer));
+
+    // Create authorization header
+    headers['authorization'] = `${algorithm} Credential=${this.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+
+    return headers;
+  }
+
+  // Make HTTP request to SNS
+  async makeRequest(action, params = {}) {
+    const queryParams = new URLSearchParams({
+      Action: action,
+      Version: '2010-03-31',
+      ...params
+    });
+
+    const url = `${this.endpoint}/?${queryParams.toString()}`;
+    const payload = '';
+    const headers = {
+      'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8'
+    };
+
+    // Sign the request
+    const signedHeaders = await this.sign('GET', url, headers, payload);
+
+    try {
+      const response = await fetch(url, {
+        method: 'GET',
+        headers: signedHeaders
+      });
+
+      const text = await response.text();
+      
+      if (!response.ok) {
+        throw new Error(`SNS API Error: ${response.status} - ${text}`);
+      }
+
+      return this.parseXMLResponse(text);
+    } catch (error) {
+      throw new Error(`SNS Request failed: ${error.message}`);
+    }
+  }
+
+  // Parse XML response (simplified for Cloudflare Workers)
+  parseXMLResponse(xmlText) {
+    // Simple XML parsing for common SNS responses
+    // Note: DOMParser is not available in Cloudflare Workers, so we'll use regex parsing
+    // This is a simplified parser for SNS responses
+    
+    // Handle common SNS responses using regex parsing
+    const messageIdMatch = xmlText.match(/<MessageId>([^<]+)<\/MessageId>/);
+    const topicArnMatch = xmlText.match(/<TopicArn>([^<]+)<\/TopicArn>/);
+    const subscriptionArnMatch = xmlText.match(/<SubscriptionArn>([^<]+)<\/SubscriptionArn>/);
+    
+    if (messageIdMatch) {
+      return { MessageId: messageIdMatch[1] };
+    }
+    
+    if (topicArnMatch) {
+      return { TopicArn: topicArnMatch[1] };
+    }
+    
+    if (subscriptionArnMatch) {
+      return { SubscriptionArn: subscriptionArnMatch[1] };
+    }
+    
+    // Fallback: return raw text for unknown responses
+    return { raw: xmlText };
+  }
+}
+
+// Global SNS client instance
+let defaultClient = null;
+
+// Create SNS client
+export function createClient(options = {}) {
+  defaultClient = new SNSClient(options);
+  return defaultClient;
+}
+
+// Send SMS function
+export function sendSMS(textmessage, phone, senderid, SMSType, callback, client = null) {
+  const snsClient = client || defaultClient;
+  
+  if (!snsClient) {
+    return callback({ err: new Error('SNS client not initialized. Call createClient() first.') });
+  }
+
+  const params = {
+    Message: textmessage,
+    PhoneNumber: phone,
+    'MessageAttributes.entry.1.Name': 'AWS.SNS.SMS.SenderID',
+    'MessageAttributes.entry.1.Value.DataType': 'String',
+    'MessageAttributes.entry.1.Value.StringValue': senderid,
+    'MessageAttributes.entry.2.Name': 'AWS.SNS.SMS.SMSType',
+    'MessageAttributes.entry.2.Value.DataType': 'String',
+    'MessageAttributes.entry.2.Value.StringValue': SMSType
+  };
+
+  snsClient.makeRequest('Publish', params)
+    .then(response => {
+      callback(undefined, response.MessageId);
+    })
+    .catch(error => {
+      callback({ err: error, 'err.stack': error.stack });
+    });
+}
+
+// Export for compatibility
+export default {
+  createClient,
+  sendSMS
+}; 

package/src/verify-phone-server.js

@@ -0,0 +1,448 @@
+/**
+ * SMS API Server using Hono and AWS SNS.
+ *
+ * - Provides endpoints for sending and verifying SMS codes.
+ * - Supports general SMS messaging with custom text.
+ * - Supports API key authentication.
+ * - Optionally blocks VoIP numbers using a phone lookup API.
+ * - Designed for Cloudflare Workers, but testable locally.
+ *
+ * @module verify-phone-server
+ */
+
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { logger } from "hono/logger";
+import { secureHeaders } from "hono/secure-headers";
+import { rateLimiter } from "hono-rate-limiter";
+import { swaggerUI } from "@hono/swagger-ui";
+import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
+import verifyPhone from "./verify-phone.ts";
+
+// Create the main app
+const app = new OpenAPIHono();
+
+// Middleware
+app.use("*", logger());
+app.use("*", secureHeaders());
+app.use("*", cors({
+  origin: ["*"],
+  allowMethods: ["GET", "POST", "OPTIONS"],
+  allowHeaders: ["Content-Type", "Authorization", "X-API-Key"],
+  maxAge: 86400,
+}));
+
+// Rate limiting - lazy loaded to avoid global scope issues
+const createRateLimiter = () => rateLimiter({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100, // limit each IP to 100 requests per windowMs
+  message: "Too many requests from this IP, please try again later.",
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+
+// Apply rate limiting only when the middleware is actually used
+app.use("*", async (c, next) => {
+  const limiter = createRateLimiter();
+  return limiter(c, next);
+});
+
+// API Key authentication middleware
+const authenticateApiKey = async (c, next) => {
+  const apiKey = c.req.header("X-API-Key") || c.req.header("Authorization")?.replace("Bearer ", "");
+  const expectedApiKey = c.env?.API_KEY;
+  
+  if (!apiKey || apiKey !== expectedApiKey) {
+    return c.json({
+      success: false,
+      error: "Unauthorized",
+      message: "Invalid or missing API key"
+    }, 401);
+  }
+  
+  await next();
+};
+
+// Health check endpoint
+app.get("/", (c) => {
+  return c.json({
+    success: true,
+    message: "SMS Verification API",
+    version: "1.0.0",
+    endpoints: {
+      health: "/health",
+      send: "/api/send",
+      verify: "/api/verify",
+      docs: "/docs"
+    }
+  });
+});
+
+// Health check
+app.get("/health", (c) => {
+  return c.json({
+    success: true,
+    status: "healthy",
+    timestamp: new Date().toISOString(),
+    uptime: "N/A" // process.uptime() not available in Cloudflare Workers
+  });
+});
+
+// Generate verification code
+function generateCode(length = 6) {
+  const chars = "0123456789";
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+// Send SMS verification code
+const sendRoute = createRoute({
+  method: "post",
+  path: "/api/send",
+  security: [{ apiKey: [] }],
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            phoneNumber: z.string().min(1, "Phone number is required"),
+            code: z.string().optional(),
+            blockVoip: z.boolean().optional().default(false),
+            senderId: z.string().optional().default("Verify"),
+            messageTemplate: z.string().optional(),
+            smsType: z.enum(["Transactional", "Promotional"]).optional().default("Transactional")
+          })
+        }
+      }
+    }
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            success: z.boolean(),
+            message: z.string().optional(),
+            messageId: z.string().optional(),
+            code: z.string().optional(),
+            phoneNumber: z.string().optional(),
+            expiresIn: z.number().optional(),
+            error: z.string().optional(),
+            details: z.string().optional(),
+            isVoip: z.boolean().optional()
+          })
+        }
+      },
+      description: "SMS sent successfully"
+    },
+    400: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            success: z.boolean(),
+            error: z.string(),
+            details: z.string().optional()
+          })
+        }
+      },
+      description: "Bad request"
+    },
+    401: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            success: z.boolean(),
+            error: z.string(),
+            message: z.string()
+          })
+        }
+      },
+      description: "Unauthorized"
+    }
+  }
+});
+
+app.openapi(sendRoute, async (c) => {
+  try {
+    const body = await c.req.json();
+    const { phoneNumber, code, blockVoip, senderId, messageTemplate, smsType } = body;
+
+    // Generate code if not provided
+    const verificationCode = code || generateCode();
+
+    // Get AWS credentials from environment
+    const awsCredentials = {
+      accessKeyId: c.env?.AWS_ACCESS_KEY_ID,
+      secretAccessKey: c.env?.AWS_SECRET_ACCESS_KEY,
+      awsRegion: c.env?.AWS_REGION || "us-east-1"
+    };
+
+    // Validate AWS credentials
+    if (!awsCredentials.accessKeyId || !awsCredentials.secretAccessKey) {
+      return c.json({
+        success: false,
+        error: "AWS credentials not configured",
+        details: "Please set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables"
+      }, 500);
+    }
+
+    // Send verification SMS
+    const result = await verifyPhone({
+      phoneNumber,
+      code: verificationCode,
+      ...awsCredentials,
+      blockVoip,
+      senderId: senderId || c.env?.SMS_SENDER_ID || "Verify",
+      messageTemplate,
+      smsType
+    });
+
+    if (result.success) {
+      return c.json({
+        success: true,
+        message: result.message,
+        messageId: result.messageId,
+        code: result.code,
+        phoneNumber: result.phoneNumber,
+        expiresIn: result.expiresIn
+      });
+    } else {
+      return c.json({
+        success: false,
+        error: result.error,
+        details: result.details,
+        isVoip: result.isVoip
+      }, 400);
+    }
+
+  } catch (error) {
+    return c.json({
+      success: false,
+      error: "Internal server error",
+      details: error.message
+    }, 500);
+  }
+});
+
+// Verify SMS code (mock endpoint for demonstration)
+const verifyRoute = createRoute({
+  method: "post",
+  path: "/api/verify",
+  security: [{ apiKey: [] }],
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            phoneNumber: z.string().min(1, "Phone number is required"),
+            code: z.string().min(1, "Verification code is required")
+          })
+        }
+      }
+    }
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            success: z.boolean(),
+            message: z.string().optional(),
+            verified: z.boolean().optional(),
+            error: z.string().optional()
+          })
+        }
+      },
+      description: "Code verified successfully"
+    },
+    400: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            success: z.boolean(),
+            error: z.string()
+          })
+        }
+      },
+      description: "Bad request"
+    }
+  }
+});
+
+app.openapi(verifyRoute, async (c) => {
+  try {
+    const body = await c.req.json();
+    const { phoneNumber, code } = body;
+
+    // This is a mock verification - in a real app, you'd store codes in a database
+    // and verify them against stored values with proper expiration handling
+    
+    // For demo purposes, we'll just return success
+    // In production, implement proper code storage and verification
+    return c.json({
+      success: true,
+      message: "Code verified successfully",
+      verified: true
+    });
+
+  } catch (error) {
+    return c.json({
+      success: false,
+      error: "Internal server error",
+      details: error.message
+    }, 500);
+  }
+});
+
+// General SMS sending endpoint
+const generalSmsRoute = createRoute({
+  method: "post",
+  path: "/api/sms",
+  security: [{ apiKey: [] }],
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            phoneNumber: z.string().min(1, "Phone number is required"),
+            message: z.string().min(1, "Message is required"),
+            senderId: z.string().optional().default("Verify"),
+            smsType: z.enum(["Transactional", "Promotional"]).optional().default("Transactional")
+          })
+        }
+      }
+    }
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            success: z.boolean(),
+            message: z.string().optional(),
+            messageId: z.string().optional(),
+            phoneNumber: z.string().optional(),
+            error: z.string().optional(),
+            details: z.string().optional()
+          })
+        }
+      },
+      description: "SMS sent successfully"
+    }
+  }
+});
+
+app.openapi(generalSmsRoute, async (c) => {
+  try {
+    const body = await c.req.json();
+    const { phoneNumber, message, senderId, smsType } = body;
+
+    // Get AWS credentials from environment
+    const awsCredentials = {
+      accessKeyId: c.env?.AWS_ACCESS_KEY_ID,
+      secretAccessKey: c.env?.AWS_SECRET_ACCESS_KEY,
+      awsRegion: c.env?.AWS_REGION || "us-east-1"
+    };
+
+    // Validate AWS credentials
+    if (!awsCredentials.accessKeyId || !awsCredentials.secretAccessKey) {
+      return c.json({
+        success: false,
+        error: "AWS credentials not configured",
+        details: "Please set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables"
+      }, 500);
+    }
+
+    // Send general SMS
+    const result = await verifyPhone({
+      phoneNumber,
+      code: "GENERAL", // Use a placeholder code for general SMS
+      ...awsCredentials,
+      blockVoip: false,
+      senderId: senderId || c.env?.SMS_SENDER_ID || "Verify",
+      messageTemplate: message,
+      smsType
+    });
+
+    if (result.success) {
+      return c.json({
+        success: true,
+        message: "SMS sent successfully",
+        messageId: result.messageId,
+        phoneNumber: result.phoneNumber
+      });
+    } else {
+      return c.json({
+        success: false,
+        error: result.error,
+        details: result.details
+      }, 400);
+    }
+
+  } catch (error) {
+    return c.json({
+      success: false,
+      error: "Internal server error",
+      details: error.message
+    }, 500);
+  }
+});
+
+// OpenAPI documentation
+app.doc("/docs", {
+  openapi: "3.0.0",
+  info: {
+    title: "SMS Verification API",
+    version: "1.0.0",
+    description: "API for sending SMS verification codes using AWS SNS"
+  },
+  servers: [
+    {
+      url: "https://sms-verification-api.your-subdomain.workers.dev",
+      description: "Production server"
+    },
+    {
+      url: "http://localhost:8787",
+      description: "Development server"
+    }
+  ],
+  components: {
+    securitySchemes: {
+      apiKey: {
+        type: "apiKey",
+        name: "X-API-Key",
+        in: "header"
+      }
+    }
+  }
+});
+
+// Swagger UI
+app.get("/docs", swaggerUI({ url: "/docs" }));
+
+// Apply authentication to all API routes
+app.use("/api/*", authenticateApiKey);
+
+// Error handling
+app.onError((err, c) => {
+  console.error("Server error:", err);
+  return c.json({
+    success: false,
+    error: "Internal server error",
+    details: err.message
+  }, 500);
+});
+
+// 404 handler
+app.notFound((c) => {
+  return c.json({
+    success: false,
+    error: "Not found",
+    message: "The requested endpoint does not exist"
+  }, 404);
+});
+
+export default app;