verify-phone-sms 0.9.4

package/docs/content/docs/API_AUTHENTICATION.md

@@ -0,0 +1,91 @@
+---
+title: API Authentication
+---
+
+This SMS Verification API requires authentication using an API key for all endpoints except:
+- `/health` - Health check endpoint
+- `/` - Swagger UI documentation (root path)
+- `/openapi.json` - OpenAPI specification
+
+## API Key
+
+Your API key is: `sk_test_1234567890abcdef1234567890abcdef`
+
+## Authentication Methods
+
+You can provide your API key in one of two ways:
+
+### Method 1: X-API-Key Header (Recommended)
+```bash
+curl -X POST https://your-worker.workers.dev/api/send-verification \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: sk_test_1234567890abcdef1234567890abcdef" \
+  -d '{"phoneNumber": "+1234567890"}'
+```
+
+### Method 2: Authorization Header (Bearer Token)
+```bash
+curl -X POST https://your-worker.workers.dev/api/send-verification \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk_test_1234567890abcdef1234567890abcdef" \
+  -d '{"phoneNumber": "+1234567890"}'
+```
+
+## JavaScript/Node.js Examples
+
+### Using X-API-Key Header
+```javascript
+const response = await fetch('https://your-worker.workers.dev/api/send-verification', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-API-Key': 'sk_test_1234567890abcdef1234567890abcdef'
+  },
+  body: JSON.stringify({
+    phoneNumber: '+1234567890'
+  })
+});
+```
+
+### Using Authorization Header
+```javascript
+const response = await fetch('https://your-worker.workers.dev/api/send-verification', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': 'Bearer sk_test_1234567890abcdef1234567890abcdef'
+  },
+  body: JSON.stringify({
+    phoneNumber: '+1234567890'
+  })
+});
+```
+
+## Error Responses
+
+### Missing API Key (401 Unauthorized)
+```json
+{
+  "error": "API key required",
+  "message": "Please provide your API key in the Authorization header (Bearer token) or X-API-Key header"
+}
+```
+
+### Invalid API Key (401 Unauthorized)
+```json
+{
+  "error": "Invalid API key",
+  "message": "The provided API key is invalid"
+}
+```
+
+## Security Notes
+
+- Keep your API key secure and do not share it publicly
+- The API key is stored as a secret in Cloudflare Workers
+- All API requests should be made over HTTPS
+- Consider rotating your API key periodically for enhanced security
+
+## Testing
+
+You can test the API using the Swagger UI at the root path `/`, which will prompt you to enter your API key in the "Authorize" section. 

package/docs/content/docs/DEPLOYMENT.md

@@ -0,0 +1,181 @@
+---
+title: Cloudflare Workers Deployment Guide
+---
+
+This guide will help you deploy the SMS Verification API to Cloudflare Workers using Wrangler.
+
+## Prerequisites
+
+1. **Cloudflare Account**: Sign up at [cloudflare.com](https://cloudflare.com)
+2. **Wrangler CLI**: Install Wrangler globally
+   ```bash
+   npm install -g wrangler
+   ```
+3. **AWS Account**: You'll need AWS credentials for SNS SMS sending
+
+## Setup Steps
+
+### 1. Install Dependencies
+```bash
+npm install
+```
+
+### 2. Login to Cloudflare
+```bash
+wrangler login
+```
+
+### 3. Configure AWS Credentials
+Set your AWS credentials as Cloudflare Workers secrets:
+```bash
+wrangler secret put AWS_ACCESS_KEY_ID
+# Enter your AWS Access Key ID when prompted
+
+wrangler secret put AWS_SECRET_ACCESS_KEY
+# Enter your AWS Secret Access Key when prompted
+```
+
+### 4. Update Configuration
+Edit `wrangler.toml` to match your Cloudflare account:
+```toml
+name = "your-sms-verification-api"
+main = "src/index.js"
+compatibility_date = "2024-01-01"
+
+[env.production]
+name = "your-sms-verification-api"
+
+[env.staging]
+name = "your-sms-verification-api-staging"
+
+[vars]
+AWS_REGION = "us-east-1"
+SMS_SENDER_ID = "YourApp"
+```
+
+### 5. Update Server URLs
+In `src/index.js`, update the server URLs in the OpenAPI configuration:
+```javascript
+servers: [
+  {
+    url: 'https://your-sms-verification-api.your-subdomain.workers.dev',
+    description: 'Production server',
+  },
+  {
+    url: 'https://your-sms-verification-api-staging.your-subdomain.workers.dev',
+    description: 'Staging server',
+  },
+],
+```
+
+## Development
+
+### Local Development
+```bash
+npm run dev
+```
+This starts a local development server at `http://localhost:8787`
+
+### Testing
+```bash
+npm run test
+```
+
+## Deployment
+
+### Deploy to Staging
+```bash
+npm run deploy:staging
+```
+
+### Deploy to Production
+```bash
+npm run deploy:production
+```
+
+### Deploy to Default Environment
+```bash
+npm run deploy
+```
+
+## Environment Variables
+
+### Required Secrets (set with `wrangler secret put`)
+- `AWS_ACCESS_KEY_ID`: Your AWS Access Key ID
+- `AWS_SECRET_ACCESS_KEY`: Your AWS Secret Access Key
+
+### Optional Variables (set in wrangler.toml)
+- `AWS_REGION`: AWS region (default: us-east-1)
+- `SMS_SENDER_ID`: Sender ID for SMS messages (default: Verify)
+
+## Production Considerations
+
+### 1. Use Cloudflare KV for Storage
+Replace in-memory storage with Cloudflare KV for production:
+
+```javascript
+// Add KV binding to wrangler.toml
+[[kv_namespaces]]
+binding = "VERIFICATION_CODES"
+id = "your-kv-namespace-id"
+preview_id = "your-preview-kv-namespace-id"
+
+// Update storage in src/index.js
+const verificationCodes = env.VERIFICATION_CODES;
+```
+
+### 2. Custom Domain
+Add a custom domain in the Cloudflare dashboard and update your `wrangler.toml`:
+```toml
+[env.production]
+name = "your-sms-verification-api"
+routes = [
+  { pattern = "api.yourdomain.com", zone_name = "yourdomain.com" }
+]
+```
+
+### 3. Rate Limiting
+Consider using Cloudflare's built-in rate limiting or implement more sophisticated rate limiting with KV storage.
+
+## Monitoring
+
+### Logs
+View logs in the Cloudflare dashboard or using Wrangler:
+```bash
+wrangler tail
+```
+
+### Analytics
+Monitor your API usage in the Cloudflare dashboard under Workers & Pages.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **CORS Errors**: The API is configured to allow all origins (`*`). Adjust in `src/index.js` if needed.
+
+2. **AWS Credentials**: Ensure your AWS credentials have SNS SMS sending permissions.
+
+3. **Memory Limits**: Cloudflare Workers have memory limits. The current implementation uses in-memory storage which resets on each request.
+
+4. **Timeout Issues**: Workers have a 30-second timeout. Ensure your SNS requests complete within this time.
+
+### Debug Mode
+Enable debug logging by setting the log level in your Worker:
+```javascript
+app.use('*', logger({ level: 'debug' }));
+```
+
+## Security
+
+- AWS credentials are stored as encrypted secrets
+- CORS is configured for cross-origin requests
+- Rate limiting is implemented to prevent abuse
+- Input validation is performed on all endpoints
+
+## Cost Optimization
+
+- Cloudflare Workers are pay-per-request
+- Monitor your usage in the Cloudflare dashboard
+- Consider implementing caching for frequently accessed data
+- Use KV storage efficiently to minimize read/write operations 

package/docs/content/docs/api/post.mdx

@@ -0,0 +1,35 @@
+---
+title: Send SMS verification code
+---
+
+
+![phone_logo](https://i.imgur.com/2adfBGT.png)
+
+
+A comprehensive SMS verification API using AWS SNS HTTP API with Hono server on Cloudflare Workers. The API is fully documented and driven by an OpenAPI 3.0 spec, available at:
+## Features
+- **Cloudflare Workers**: Serverless deployment with global edge network
+- **Modern OpenAPI-driven contract**: Fully documented API with Swagger UI
+- **SMS verification with optional custom code**: Send random or custom verification codes
+- **VoIP number blocking**: Optional protection against VoIP numbers using phone lookup API
+- **Code verification endpoint**: Verify submitted codes with attempt tracking
+- **Health check endpoint**: Monitor API status
+- **API Key Authentication**: Secure access control for all endpoints
+- **Strong input validation**: E.164 phone numbers, 6-digit codes
+- **Rate limiting and error handling**: Built-in protection against abuse
+- **More info like names, emails**: See [Trestle](https://trestle-api.redoc.ly/Current/#section/Overview)
+- **MIT licensed**: Open source and free to use
+
+
+
+#### Send Verification Code
+`GET /api/send-verification`
+- Sends a 6-digit verification code to the specified phone number via SMS.
+- Optionally accepts a custom code (for testing or admin use).
+- Optionally blocks VoIP numbers using phone lookup API.
+
+**Query Parameters:**
+- `phoneNumber` (required): Phone number in E.164 format (e.g., +1234567890)
+- `code` (optional): Custom 6-digit verification code
+- `blockVoip` (optional): Boolean flag to block VoIP numbers
+<APIPage document={"openapi.json"} operations={[{"path":"/api/send-verification","method":"post"}]} webhooks={[]} hasHead={false} />

package/docs/content/docs/api/verify.mdx

@@ -0,0 +1,34 @@
+---
+title: Verify SMS code
+---
+
+#### Verify Code
+`GET /api/verify-code`
+- Verifies the submitted code against the sent verification code.
+
+**Query Parameters:**
+- `phoneNumber` (required): Phone number in E.164 format
+- `code` (required): 6-digit verification code
+
+**Example Request:**
+```
+GET /api/verify-code?phoneNumber=%2B1234567890&code=654321
+```
+
+**Response (success):**
+```json
+{
+  "success": true,
+  "message": "Phone number verified successfully",
+  "verificationToken": "unique-verification-token",
+  "phoneNumber": "+1234567890"
+}
+```
+
+**Response (error):**
+```json
+{
+  "error": "Invalid verification code",
+  "attemptsRemaining": 3
+}
+```

package/docs/content/docs/meta.json

@@ -0,0 +1,8 @@
+{
+  "pages": [
+    "api/post",
+    "api/verify",
+    "..."
+
+  ]
+}

package/docs/content/docs/verify-legal-name.md

@@ -0,0 +1,339 @@
+---
+title: Identity Verification API Demo
+---
+
+A comprehensive identity verification system that uses TrestleIQ APIs to validate phone numbers, addresses, and generate knowledge-based authentication questions.
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Node.js or Bun runtime
+- TrestleIQ API key
+
+### Installation
+```bash
+# Install dependencies
+npm install hono @hono/zod-openapi zod
+# or
+bun add hono @hono/zod-openapi zod
+
+# Set your TrestleIQ API key
+export TRESTLE_API_KEY=your_api_key_here
+
+# Run the server
+bun run server.js
+# or
+node server.js
+```
+
+### Server Endpoints
+- 🏠 `http://localhost:3000` - Server root
+- 📊 `http://localhost:3000/health` - Health check
+- 📚 `http://localhost:3000/swagger` - Interactive API documentation
+- 🔍 `http://localhost:3000/doc` - OpenAPI specification
+- 🎮 `http://localhost:3000/demo` - Live demo with sample data
+- ✅ `POST http://localhost:3000/verify-identity` - Main verification endpoint
+
+## 🎯 How It Works
+
+### The Verification Process
+
+1. **Input Collection**: Accept phone number, legal name, and current address
+2. **Multi-API Lookup**: Query TrestleIQ APIs in parallel for comprehensive data
+3. **Historical Analysis**: Extract previous addresses, phone numbers, and associated names
+4. **Scoring Algorithm**: Calculate confidence score (0-100) based on data matches
+5. **Question Generation**: Create knowledge-based questions from historical data
+6. **Recommendations**: Provide actionable next steps based on verification results
+
+### Scoring System (100 Points Total)
+
+| Category | Max Points | Criteria |
+|----------|------------|----------|
+| **Phone Validation** | 30 | Valid number (15 pts) + Line type (10 pts) + Non-commercial (5 pts) |
+| **Name Matching** | 40 | Exact match (40 pts) or Partial match (20 pts) |
+| **Address Validation** | 30 | Valid address (15 pts) + Active delivery (10 pts) + Residential (5 pts) |
+
+### Score Interpretation
+- **🔴 0-29**: High risk - Request additional ID documents
+- **🟡 30-59**: Medium risk - Manual review recommended  
+- **🟢 60-79**: Low risk - Standard verification process
+- **✅ 80-100**: Very low risk - High confidence verification
+
+## 📝 API Usage Examples
+
+### Sample Request
+```bash
+curl -X POST http://localhost:3000/verify-identity \
+  -H "Content-Type: application/json" \
+  -d '{
+    "phone_number": "2069735100",
+    "legal_name": "John Smith", 
+    "current_address": {
+      "street_line_1": "123 Main St",
+      "city": "Seattle",
+      "state_code": "WA", 
+      "postal_code": "98101",
+      "country_code": "US"
+    }
+  }'
+```
+
+### Sample Response
+```json
+{
+  "verification_score": 75,
+  "name_match_found": true,
+  "phone_validated": true,
+  "address_validated": true,
+  "questions": [
+    {
+      "id": "addr_1703123456789",
+      "question": "Which of the following addresses have you lived at in the past?",
+      "type": "address_history",
+      "options": [
+        "456 Oak Ave, Seattle, WA",
+        "789 Pine St, Tacoma, WA", 
+        "123 Fake St, Nowhere, CA",
+        "101 False Blvd, Bogus, NY",
+        "202 Phony Way, Unreal, WA"
+      ]
+    },
+    {
+      "id": "phone_1703123456790",
+      "question": "Which of the following phone numbers have you previously used?", 
+      "type": "phone_history",
+      "options": [
+        "2065551234",
+        "4255559876",
+        "5551234567",
+        "8889876543",
+        "None of the above"
+      ]
+    },
+    {
+      "id": "name_1703123456791",
+      "question": "Are any of the following names associated with you (maiden name, nickname, etc.)?",
+      "type": "name_verification", 
+      "options": [
+        "J. Smith",
+        "Johnny Smith",
+        "John S. Smith",
+        "Jon Smith",
+        "None of the above"
+      ]
+    }
+  ],
+  "historical_data": {
+    "previous_addresses": [
+      "456 Oak Ave, Seattle, WA",
+      "789 Pine St, Tacoma, WA",
+      "321 Cedar Ln, Bellevue, WA"
+    ],
+    "previous_phones": [
+      "2065551234", 
+      "4255559876"
+    ],
+    "associated_names": [
+      "J. Smith",
+      "Johnny Smith", 
+      "John S. Smith"
+    ]
+  },
+  "recommendations": [
+    "Proceed with standard verification process",
+    "Consider asking verification questions to increase confidence"
+  ]
+}
+```
+
+## 🧠 Smart Features
+
+### Dynamic Question Generation
+The system intelligently creates multiple-choice questions by:
+- **Mixing real historical data** with plausible decoy options
+- **Randomizing question order** to prevent pattern recognition
+- **Balancing difficulty** - not too easy, not impossible
+- **Including safety options** like "None of the above"
+
+### Historical Data Analysis
+Extracts comprehensive historical information:
+- **Previous addresses** from phone and person records
+- **Associated phone numbers** across different time periods  
+- **Name variations** including nicknames, initials, and maiden names
+- **Cross-references data** across multiple API sources for accuracy
+
+### Risk-Based Recommendations
+Provides actionable recommendations based on verification results:
+- **Document requests** for low-scoring verifications
+- **VOIP warnings** for non-fixed internet phone numbers
+- **Manual review triggers** for medium-confidence scores
+- **Approval suggestions** for high-confidence verifications
+
+## 🔧 Advanced Configuration
+
+### Environment Variables
+```bash
+TRESTLE_API_KEY=your_trestle_api_key    # Required: TrestleIQ API key
+PORT=3000                               # Optional: Server port (default: 3000)
+```
+
+### Custom Scoring Weights
+You can modify the scoring algorithm by adjusting the point values in the `calculateVerificationScore` function:
+
+```javascript
+// Phone validation scoring
+if (phoneResult?.is_valid) {
+  score += 15  // Base validation points
+  if (phoneResult.line_type === 'Mobile' || phoneResult.line_type === 'Landline') {
+    score += 10  // Reliable line type bonus  
+  }
+  if (!phoneResult.is_commercial) {
+    score += 5   // Residential number bonus
+  }
+}
+```
+
+### Question Customization
+Modify question generation in `generateVerificationQuestions`:
+- Adjust number of real vs. fake options
+- Change question phrasing
+- Add new question types
+- Customize difficulty levels
+
+## 🎮 Try the Demo
+
+Visit `http://localhost:3000/demo` to see a live example with sample data, or use the interactive Swagger UI at `http://localhost:3000/swagger` to test with your own data.
+
+### Demo Scenarios
+
+#### High Confidence Scenario (Score: 85+)
+```json
+{
+  "phone_number": "2069735100",
+  "legal_name": "Waidong L Syrws", 
+  "current_address": {
+    "street_line_1": "100 Syrws St",
+    "city": "Lynden", 
+    "state_code": "WA",
+    "postal_code": "98264"
+  }
+}
+```
+
+#### Medium Confidence Scenario (Score: 50-70)  
+```json
+{
+  "phone_number": "5551234567",
+  "legal_name": "Jane Doe",
+  "current_address": {
+    "street_line_1": "789 Unknown Ave", 
+    "city": "Somewhere",
+    "state_code": "CA",
+    "postal_code": "90210" 
+  }
+}
+```
+
+#### Low Confidence Scenario (Score: 20-40)
+```json
+{
+  "phone_number": "1234567890", 
+  "legal_name": "Fake Person",
+  "current_address": {
+    "street_line_1": "123 Nonexistent St",
+    "city": "Nowhere", 
+    "state_code": "XX",
+    "postal_code": "00000"
+  }
+}
+```
+
+## 🛡️ Security & Privacy
+
+- **No data storage**: All verification data is processed in-memory only
+- **API key protection**: TrestleIQ API key stored securely in environment variables  
+- **CORS enabled**: Configurable cross-origin request handling
+- **Error handling**: Comprehensive error handling without data leakage
+- **Rate limiting**: Inherits TrestleIQ API rate limits for responsible usage
+
+## 🔗 Integration Examples
+
+### React Frontend Integration
+```javascript
+const verifyIdentity = async (personData) => {
+  const response = await fetch('/verify-identity', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(personData)
+  })
+  return response.json()
+}
+
+// Usage
+const result = await verifyIdentity({
+  phone_number: "2069735100",
+  legal_name: "John Smith",
+  current_address: { /* address data */ }
+})
+
+if (result.verification_score >= 80) {
+  // High confidence - proceed with onboarding
+} else if (result.questions.length > 0) {
+  // Show verification questions
+} else {
+  // Request additional documentation
+}
+```
+
+### Node.js Backend Integration
+```javascript
+import { verifyIdentity } from './verification-functions.js'
+
+app.post('/onboard-user', async (req, res) => {
+  try {
+    const verification = await verifyIdentity(req.body, process.env.TRESTLE_API_KEY)
+    
+    // Store verification result
+    await db.users.update(req.body.userId, {
+      verification_score: verification.verification_score,
+      verification_status: verification.verification_score >= 70 ? 'approved' : 'pending',
+      questions: verification.questions
+    })
+    
+    res.json(verification)
+  } catch (error) {
+    res.status(500).json({ error: 'Verification failed' })
+  }
+})
+```
+
+## 📊 API Response Details
+
+### Verification Questions Types
+- **`address_history`**: Multiple choice questions about previous addresses
+- **`phone_history`**: Questions about previously used phone numbers  
+- **`name_verification`**: Questions about name variations and associations
+
+### Recommendation Categories
+- **Identity Documents**: When additional ID verification is needed
+- **Manual Review**: When human verification should be considered
+- **Technical Warnings**: VOIP numbers, invalid addresses, etc.
+- **Process Guidance**: Next steps based on confidence level
+
+## 🤝 Contributing
+
+This demo showcases the core functionality. For production use, consider:
+- Adding database persistence for verification results
+- Implementing user authentication and session management
+- Adding webhook support for async verification workflows  
+- Enhancing question complexity and variety
+- Adding support for international phone numbers and addresses
+
+## 📞 Support
+
+For TrestleIQ API questions, visit [TrestleIQ Documentation](https://api.trestleiq.com)
+For implementation questions, check the inline code comments and Swagger documentation.
+
+---
+
+**Ready to verify identities?** Start the server and visit the demo endpoint! 🎯

package/docs/lib/source.ts

@@ -0,0 +1,14 @@
+import { createMDXSource } from 'fumadocs-mdx';
+import { loader } from 'fumadocs-core/source';
+import { attachFile, createOpenAPI } from 'fumadocs-openapi/server';
+import { docs, meta } from '@/.source';
+
+export const source = loader({
+  baseUrl: '/docs',
+  source: createMDXSource(docs, meta),
+  pageTree: {
+    attachFile,
+  },
+});
+
+export const openapi = createOpenAPI();