sms-verification-api 0.9.1

package/src/identity-verification-server.ts

@@ -0,0 +1,553 @@
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+import { logger } from 'hono/logger'
+import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi'
+
+// Input/Output Schemas
+const PersonInputSchema = z.object({
+  phone_number: z.string().min(10).max(15).describe('Phone number in E.164 or local format'),
+  legal_name: z.string().min(1).max(100).describe('Full legal name of the person'),
+  current_address: z.object({
+    street_line_1: z.string().min(1).max(1000),
+    street_line_2: z.string().max(1000).optional(),
+    city: z.string().min(1).max(500),
+    state_code: z.string().length(2),
+    postal_code: z.string().min(5).max(10),
+    country_code: z.string().length(2).default('US')
+  }).describe('Current address information')
+})
+
+const VerificationResponseSchema = z.object({
+  verification_score: z.number().min(0).max(100).describe('Confidence score 0-100'),
+  name_match_found: z.boolean(),
+  phone_validated: z.boolean(),
+  address_validated: z.boolean(),
+  questions: z.array(z.object({
+    id: z.string(),
+    question: z.string(),
+    type: z.enum(['address_history', 'phone_history', 'name_verification']),
+    options: z.array(z.string()).optional()
+  })),
+  historical_data: z.object({
+    previous_addresses: z.array(z.string()),
+    previous_phones: z.array(z.string()),
+    associated_names: z.array(z.string())
+  }),
+  recommendations: z.array(z.string()).describe('Suggestions for additional verification')
+})
+
+// TrestleIQ API Functions
+async function makeRequest(endpoint, params, apiKey, baseUrl = 'https://api.trestleiq.com') {
+  const url = new URL(endpoint, baseUrl)
+  Object.entries(params).forEach(([key, value]) => {
+    if (value) url.searchParams.set(key, value)
+  })
+
+  const response = await fetch(url.toString(), {
+    headers: {
+      'x-api-key': apiKey,
+      'Accept': 'application/json'
+    }
+  })
+
+  if (!response.ok) {
+    throw new Error(`TrestleIQ API error: ${response.status} ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+function reversePhone(phoneNumber, apiKey, hints = {}) {
+  return makeRequest('/3.2/phone', {
+    phone: phoneNumber,
+    'phone.country_hint': 'US',
+    ...(hints.name && { 'phone.name_hint': hints.name }),
+    ...(hints.postalCode && { 'phone.postal_code_hint': hints.postalCode })
+  }, apiKey)
+}
+
+function findPerson(name, address, apiKey) {
+  return makeRequest('/3.1/person', {
+    name,
+    'address.street_line_1': address.street_line_1,
+    'address.city': address.city,
+    'address.state_code': address.state_code,
+    'address.postal_code': address.postal_code,
+    'address.country_code': address.country_code || 'US'
+  }, apiKey)
+}
+
+function reverseAddress(address, apiKey) {
+  return makeRequest('/3.1/location', {
+    street_line_1: address.street_line_1,
+    ...(address.street_line_2 && { street_line_2: address.street_line_2 }),
+    city: address.city,
+    state_code: address.state_code,
+    postal_code: address.postal_code,
+    country_code: address.country_code || 'US'
+  }, apiKey)
+}
+
+// Utility Functions
+function normalizeName(name) {
+  return name.toLowerCase().replace(/[^a-z\s]/g, '').trim()
+}
+
+function extractHistoricalData(phoneResult, personResult, addressResult) {
+  const previousAddresses = []
+  const previousPhones = []
+  const associatedNames = []
+
+  // Extract from phone result
+  if (phoneResult?.owners) {
+    phoneResult.owners.forEach(owner => {
+      if (owner.name) associatedNames.push(owner.name)
+      if (owner.addresses) {
+        owner.addresses.forEach(addr => {
+          if (addr.street_line_1 && addr.city && addr.state_code) {
+            previousAddresses.push(`${addr.street_line_1}, ${addr.city}, ${addr.state_code}`)
+          }
+        })
+      }
+      if (owner.phones) {
+        owner.phones.forEach(phone => {
+          if (phone.phone_number) previousPhones.push(phone.phone_number)
+        })
+      }
+    })
+  }
+
+  // Extract from person result
+  if (personResult?.person) {
+    personResult.person.forEach(person => {
+      if (person.addresses) {
+        person.addresses.forEach(addr => {
+          if (addr.street_line_1 && addr.city && addr.state_code) {
+            previousAddresses.push(`${addr.street_line_1}, ${addr.city}, ${addr.state_code}`)
+          }
+        })
+      }
+      if (person.phones) {
+        person.phones.forEach(phone => {
+          if (phone.phone_number) previousPhones.push(phone.phone_number)
+        })
+      }
+    })
+  }
+
+  // Extract from address result
+  if (addressResult?.current_residents) {
+    addressResult.current_residents.forEach(resident => {
+      if (resident.name) associatedNames.push(resident.name)
+    })
+  }
+
+  return {
+    previous_addresses: [...new Set(previousAddresses)].slice(0, 10),
+    previous_phones: [...new Set(previousPhones)].slice(0, 5),
+    associated_names: [...new Set(associatedNames)].slice(0, 10)
+  }
+}
+
+function checkNameMatch(personResult, phoneResult, inputName) {
+  const normalizedInputName = normalizeName(inputName)
+  
+  // Check person result
+  if (personResult?.person) {
+    for (const person of personResult.person) {
+      if (person.name && normalizeName(person.name) === normalizedInputName) {
+        return true
+      }
+    }
+  }
+
+  // Check phone owners
+  if (phoneResult?.owners) {
+    for (const owner of phoneResult.owners) {
+      if (owner.name && normalizeName(owner.name) === normalizedInputName) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+function checkPartialNameMatch(personResult, phoneResult, inputName) {
+  const inputNameParts = normalizeName(inputName).split(' ')
+  
+  const checkNameParts = (name) => {
+    const nameParts = normalizeName(name).split(' ')
+    return inputNameParts.some(part => nameParts.includes(part) && part.length > 2)
+  }
+
+  // Check person result
+  if (personResult?.person) {
+    for (const person of personResult.person) {
+      if (person.name && checkNameParts(person.name)) {
+        return true
+      }
+    }
+  }
+
+  // Check phone owners
+  if (phoneResult?.owners) {
+    for (const owner of phoneResult.owners) {
+      if (owner.name && checkNameParts(owner.name)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+function calculateVerificationScore(phoneResult, personResult, addressResult, input) {
+  let score = 0
+
+  // Phone validation (30 points max)
+  if (phoneResult?.is_valid) {
+    score += 15
+    if (phoneResult.line_type === 'Mobile' || phoneResult.line_type === 'Landline') {
+      score += 10
+    }
+    if (!phoneResult.is_commercial) {
+      score += 5
+    }
+  }
+
+  // Name matching (40 points max)
+  if (checkNameMatch(personResult, phoneResult, input.legal_name)) {
+    score += 40
+  } else if (checkPartialNameMatch(personResult, phoneResult, input.legal_name)) {
+    score += 20
+  }
+
+  // Address validation (30 points max)
+  if (addressResult?.is_valid) {
+    score += 15
+    if (addressResult.is_active) {
+      score += 10
+    }
+    if (!addressResult.is_commercial) {
+      score += 5
+    }
+  }
+
+  return Math.min(score, 100)
+}
+
+function generateFakeAddresses(count) {
+  const fakeAddresses = [
+    '123 Fake St, Nowhere, CA',
+    '456 Made Up Ave, Fictional, TX',
+    '789 Pretend Dr, Imaginary, FL',
+    '101 False Blvd, Bogus, NY',
+    '202 Phony Way, Unreal, WA'
+  ]
+  return fakeAddresses.sort(() => Math.random() - 0.5).slice(0, count)
+}
+
+function generateFakePhones(count) {
+  const fakePhones = []
+  for (let i = 0; i < count; i++) {
+    const areaCode = Math.floor(Math.random() * 900) + 100
+    const exchange = Math.floor(Math.random() * 900) + 100
+    const number = Math.floor(Math.random() * 9000) + 1000
+    fakePhones.push(`${areaCode}${exchange}${number}`)
+  }
+  return fakePhones
+}
+
+function generateVerificationQuestions(historicalData, inputName) {
+  const questions = []
+
+  // Address history questions
+  if (historicalData.previous_addresses.length > 0) {
+    const shuffledAddresses = [...historicalData.previous_addresses].sort(() => Math.random() - 0.5)
+    const realAddresses = shuffledAddresses.slice(0, 3)
+    const fakeAddresses = generateFakeAddresses(2)
+    const allOptions = [...realAddresses, ...fakeAddresses].sort(() => Math.random() - 0.5)
+
+    questions.push({
+      id: `addr_${Date.now()}`,
+      question: `Which of the following addresses have you lived at in the past?`,
+      type: 'address_history',
+      options: allOptions
+    })
+  }
+
+  // Phone history questions
+  if (historicalData.previous_phones.length > 1) {
+    const shuffledPhones = [...historicalData.previous_phones].sort(() => Math.random() - 0.5)
+    const realPhones = shuffledPhones.slice(0, 2)
+    const fakePhones = generateFakePhones(2)
+    const allOptions = [...realPhones, ...fakePhones, 'None of the above'].sort(() => Math.random() - 0.5)
+
+    questions.push({
+      id: `phone_${Date.now()}`,
+      question: `Which of the following phone numbers have you previously used?`,
+      type: 'phone_history',
+      options: allOptions
+    })
+  }
+
+  // Name verification questions
+  if (historicalData.associated_names.length > 0) {
+    const otherNames = historicalData.associated_names.filter(
+      name => normalizeName(name) !== normalizeName(inputName)
+    )
+    
+    if (otherNames.length > 0) {
+      questions.push({
+        id: `name_${Date.now()}`,
+        question: `Are any of the following names associated with you (maiden name, nickname, etc.)?`,
+        type: 'name_verification',
+        options: [...otherNames.slice(0, 4), 'None of the above']
+      })
+    }
+  }
+
+  return questions
+}
+
+function generateRecommendations(score, phoneResult, personResult, addressResult) {
+  const recommendations = []
+
+  if (score < 30) {
+    recommendations.push('Consider requesting additional identification documents')
+    recommendations.push('Verify identity through alternative methods (government ID, utility bills)')
+  } else if (score < 60) {
+    recommendations.push('Request additional verification questions')
+    recommendations.push('Consider manual review of provided information')
+  } else if (score < 80) {
+    recommendations.push('Proceed with standard verification process')
+  } else {
+    recommendations.push('High confidence verification - proceed with confidence')
+  }
+
+  if (!phoneResult?.is_valid) {
+    recommendations.push('Request alternative contact phone number')
+  }
+
+  if (!addressResult?.is_valid) {
+    recommendations.push('Verify current address with utility bill or bank statement')
+  }
+
+  if (phoneResult?.line_type === 'NonFixedVOIP') {
+    recommendations.push('VOIP number detected - consider additional verification')
+  }
+
+  return recommendations
+}
+
+// Main Verification Function
+async function verifyIdentity(input, apiKey) {
+  const { phone_number, legal_name, current_address } = input
+  
+  // Run all API calls in parallel
+  const [phoneData, personData, addressData] = await Promise.allSettled([
+    reversePhone(phone_number, apiKey, {
+      name: legal_name,
+      postalCode: current_address.postal_code
+    }),
+    findPerson(legal_name, current_address, apiKey),
+    reverseAddress(current_address, apiKey)
+  ])
+
+  // Process results
+  const phoneResult = phoneData.status === 'fulfilled' ? phoneData.value : null
+  const personResult = personData.status === 'fulfilled' ? personData.value : null
+  const addressResult = addressData.status === 'fulfilled' ? addressData.value : null
+
+  // Extract historical data
+  const historicalData = extractHistoricalData(phoneResult, personResult, addressResult)
+  
+  // Calculate verification score
+  const verificationScore = calculateVerificationScore(
+    phoneResult,
+    personResult,
+    addressResult,
+    input
+  )
+
+  // Generate verification questions
+  const questions = generateVerificationQuestions(historicalData, legal_name)
+
+  // Generate recommendations
+  const recommendations = generateRecommendations(
+    verificationScore,
+    phoneResult,
+    personResult,
+    addressResult
+  )
+
+  return {
+    verification_score: verificationScore,
+    name_match_found: checkNameMatch(personResult, phoneResult, legal_name),
+    phone_validated: phoneResult?.is_valid || false,
+    address_validated: addressResult?.is_valid || false,
+    questions,
+    historical_data: historicalData,
+    recommendations
+  }
+}
+
+// Create Hono app
+const app = new OpenAPIHono()
+
+// Middleware
+app.use('*', cors())
+app.use('*', logger())
+
+// Get API key from environment
+const getApiKey = () => {
+  const apiKey = process.env.TRESTLE_API_KEY
+  if (!apiKey) {
+    throw new Error('TRESTLE_API_KEY environment variable is required')
+  }
+  return apiKey
+}
+
+// Main API route
+const verifyIdentityRoute = createRoute({
+  method: 'post',
+  path: '/verify-identity',
+  tags: ['Identity Verification'],
+  summary: 'Verify person identity',
+  description: 'Verify a person\'s identity using phone number, legal name, and current address',
+  request: {
+    body: {
+      content: {
+        'application/json': {
+          schema: PersonInputSchema
+        }
+      }
+    }
+  },
+  responses: {
+    200: {
+      content: {
+        'application/json': {
+          schema: VerificationResponseSchema
+        }
+      },
+      description: 'Identity verification completed successfully'
+    },
+    400: {
+      description: 'Bad request - invalid input data'
+    },
+    500: {
+      description: 'Internal server error'
+    }
+  }
+})
+
+app.openapi(verifyIdentityRoute, async (c) => {
+  try {
+    const body = c.req.valid('json')
+    const apiKey = getApiKey()
+    const result = await verifyIdentity(body, apiKey)
+    
+    return c.json(result, 200)
+  } catch (error) {
+    console.error('Identity verification error:', error)
+    return c.json({ 
+      error: 'Failed to verify identity',
+      message: error instanceof Error ? error.message : 'Unknown error'
+    }, 500)
+  }
+})
+
+// Health check endpoint
+app.get('/health', (c) => {
+  return c.json({ status: 'healthy', timestamp: new Date().toISOString() })
+})
+
+// OpenAPI documentation
+app.doc('/doc', {
+  openapi: '3.0.0',
+  info: {
+    version: '1.0.0',
+    title: 'Identity Verification API',
+    description: 'API for verifying person identity using TrestleIQ data services'
+  },
+  servers: [
+    {
+      url: 'http://localhost:3000',
+      description: 'Development server'
+    }
+  ]
+})
+
+// Serve Swagger UI
+app.get('/swagger', async (c) => {
+  return c.html(`
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>Identity Verification API</title>
+      <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3.52.5/swagger-ui.css" />
+    </head>
+    <body>
+      <div id="swagger-ui"></div>
+      <script src="https://unpkg.com/swagger-ui-dist@3.52.5/swagger-ui-bundle.js"></script>
+      <script>
+        SwaggerUIBundle({
+          url: '/doc',
+          dom_id: '#swagger-ui',
+          presets: [SwaggerUIBundle.presets.standalone]
+        })
+      </script>
+    </body>
+    </html>
+  `)
+})
+
+// Demo endpoint with sample data
+app.get('/demo', async (c) => {
+  const sampleRequest = {
+    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"
+    }
+  }
+
+  try {
+    const apiKey = getApiKey()
+    const result = await verifyIdentity(sampleRequest, apiKey)
+    
+    return c.json({
+      demo_request: sampleRequest,
+      demo_response: result,
+      note: "This is a demo using sample data. Use POST /verify-identity for real verification."
+    })
+  } catch (error) {
+    return c.json({
+      demo_request: sampleRequest,
+      error: "Demo failed - check your TRESTLE_API_KEY",
+      note: "This demo requires a valid TrestleIQ API key"
+    })
+  }
+})
+
+export default app
+
+// Start server if not imported as module
+if (import.meta.main) {
+  const port = parseInt(process.env.PORT || '3000')
+  console.log(`🚀 Server running at http://localhost:${port}`)
+  console.log(`📚 API Documentation: http://localhost:${port}/swagger`)
+  console.log(`🔍 OpenAPI Spec: http://localhost:${port}/doc`)
+  console.log(`🎮 Demo Endpoint: http://localhost:${port}/demo`)
+  
+  Bun.serve({
+    port,
+    fetch: app.fetch,
+  })
+}

package/src/index.js

@@ -0,0 +1,8 @@
+/**
+ * Main entry point for the SMS Verification API server.
+ * This file is used by Cloudflare Workers and Wrangler.
+ */
+
+import app from "./verify-phone-server.js";
+
+export default app;