Twilio Verify API

.env.alfajores

@@ -92,7 +92,7 @@ ATTESTATION_BOT_MAX_ATTESTATIONS=32
 ATTESTATION_BOT_SKIP_ODIS_SALT=bot
 
 ATTESTATION_SERVICE_DOCKER_IMAGE_REPOSITORY="us.gcr.io/celo-testnet/celo-monorepo"
-ATTESTATION_SERVICE_DOCKER_IMAGE_TAG="attestation-service-v1.2.0"
+ATTESTATION_SERVICE_DOCKER_IMAGE_TAG="attestation-service-v1.3.0"
 
 TELEKOM_FROM="+14157389085"
 SMS_PROVIDERS=twilio,nexmo,telekom

packages/attestation-service/config/.env.development

@@ -7,7 +7,7 @@ ATTESTATION_SIGNER_ADDRESS=x
 
 # List all SMS providers here. They are tried from first to last, unless
 # you specify SMS_PROVIDERS_RANDOMIZED=1, in which case they are tried in a random order. 
-SMS_PROVIDERS=messagebird,twilio,nexmo
+SMS_PROVIDERS=twilio
 # SMS_PROVIDERS_RANDOMIZED=0
 
 # Optional: set a different list or order of providers for a specific country.
@@ -43,6 +43,7 @@ NEXMO_UNSUPPORTED_REGIONS=CU,SY,KP,IR,SD
 # Twilio parameters (fill in values for 'x')
 TWILIO_ACCOUNT_SID=x
 TWILIO_MESSAGING_SERVICE_SID=x
+TWILIO_VERIFY_SERVICE_SID=x
 TWILIO_AUTH_TOKEN=x
 TWILIO_UNSUPPORTED_REGIONS=CU,SY,KP,IR,SD
 

packages/attestation-service/migrations/20210625231054-attestation-v7.js

@@ -0,0 +1,32 @@
+'use strict'
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    const transaction = await queryInterface.sequelize.transaction()
+
+    try {
+      await queryInterface.addColumn('Attestations', 'appSignature', {
+        type: Sequelize.STRING,
+        allowNull: true,
+      })
+      await queryInterface.addColumn('Attestations', 'language', {
+        type: Sequelize.STRING,
+        allowNull: true,
+      })
+
+      await transaction.commit()
+    } catch (error) {
+      await transaction.rollback()
+      throw error
+    }
+  },
+  down: async (queryInterface, Sequelize) => {
+    const transaction = await queryInterface.sequelize.transaction()
+    try {
+      await queryInterface.removeColumn('Attestations', 'appSignature')
+      await queryInterface.removeColumn('Attestations', 'language')
+    } catch (error) {
+      await transaction.rollback()
+      throw error
+    }
+  },
+}

packages/attestation-service/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celo/attestation-service",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Issues attestation messages for Celo's identity protocol",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",

packages/attestation-service/src/models/attestation.ts

@@ -24,6 +24,8 @@ export interface AttestationModel extends Model {
   recordError: (error: string) => void
   failure: () => boolean
   currentError: () => string | undefined
+  appSignature: string | undefined
+  language: string | undefined
 }
 
 export interface AttestationKey {
@@ -64,6 +66,8 @@ export default (sequelize: Sequelize) => {
     errors: DataTypes.STRING,
     createdAt: DataTypes.DATE,
     completedAt: DataTypes.DATE,
+    appSignature: DataTypes.STRING,
+    language: DataTypes.STRING,
   }) as AttestationStatic
 
   model.prototype.key = function (): AttestationKey {

packages/attestation-service/src/requestHandlers/attestation.ts

@@ -152,35 +152,41 @@ class AttestationRequestHandler {
   // Main process for handling an attestation.
   async doAttestation() {
     Counters.attestationRequestsTotal.inc()
+    if (
+      !this.attestationRequest.securityCodePrefix ||
+      this.attestationRequest.securityCodePrefix.length !== 1
+    ) {
+      throw new ErrorWithResponse('Invalid securityCodePrefix', 422)
+    }
+
     let attestation = await this.findOrValidateRequest()
 
     if (attestation && attestation.message) {
       // Re-request existing attestation. In this case, security code prefix is ignored (the message sent is the same as before)
-      attestation = await rerequestAttestation(this.key, this.logger, this.sequelizeLogger)
+      attestation = await rerequestAttestation(
+        this.key,
+        this.attestationRequest.smsRetrieverAppSig,
+        this.attestationRequest.language,
+        this.attestationRequest.securityCodePrefix,
+        this.logger,
+        this.sequelizeLogger
+      )
     } else {
       // New attestation: create new attestation code, new delivery.
       const attestationCode = await this.signAttestation()
       await this.validateAttestationCode(attestationCode)
+      // This attestation code is stored in the attestation object
+      // and will be returned to the user with the get_attestation call
       const attestationCodeDeeplink = `celo://wallet/v/${toBase64(attestationCode)}`
 
-      // Determine if we're sending a security code, or the full deep link.
       let messageBase, securityCode
-      if (this.attestationRequest.securityCodePrefix) {
-        if (this.attestationRequest.securityCodePrefix.length !== 1) {
-          throw new ErrorWithResponse('Invalid securityCodePrefix', 422)
-        }
 
-        // Client is requesting a security code SMS. Generate a challenge and just store the deeplink.
-        securityCode = randomBytes(7)
-          .map((x) => x % 10)
-          .join('')
-        messageBase = `${getSecurityCodeText(this.attestationRequest.language)}: ${
-          this.attestationRequest.securityCodePrefix
-        }${securityCode}`
-      } else {
-        // Client is requesting direct SMS with the deeplink.
-        messageBase = attestationCodeDeeplink
-      }
+      // Generate a security code to be sent over SMS
+      securityCode = randomBytes(7)
+        .map((x) => x % 10)
+        .join('')
+      securityCode = `${this.attestationRequest.securityCodePrefix}${securityCode}`
+      messageBase = `${getSecurityCodeText(this.attestationRequest.language)}: ${securityCode}`
 
       let textMessage
 
@@ -200,6 +206,8 @@ class AttestationRequestHandler {
         textMessage,
         securityCode,
         attestationCodeDeeplink,
+        this.attestationRequest.smsRetrieverAppSig,
+        this.attestationRequest.language,
         this.logger,
         this.sequelizeLogger
       )

packages/attestation-service/src/requestHandlers/get_attestation.ts

@@ -77,7 +77,12 @@ class GetAttestationRequestHandler {
       }
 
       // Security code is supplied. Check it's correct.
-      if (attestation.securityCode === this.getRequest.securityCode) {
+      // Check with both methods (can remove second method after 1.3.0)
+      if (
+        attestation.securityCode &&
+        (attestation.securityCode.slice(1) === this.getRequest.securityCode ||
+          attestation.securityCode === this.getRequest.securityCode)
+      ) {
         callback(attestation, attestation.attestationCode)
         await transaction.commit()
         return

packages/attestation-service/src/requestHandlers/status.ts

@@ -53,6 +53,7 @@ export async function handleStatusRequest(
             10
           ),
           maxRerequestMins: parseInt(fetchEnvOrDefault('MAX_REREQUEST_MINS', '55'), 10),
+          twilioVerifySidProvided: !!fetchEnvOrDefault('TWILIO_VERIFY_SERVICE_SID', ''),
         })
       )
       .status(200)

packages/attestation-service/src/requestHandlers/test_attestation.ts

@@ -54,8 +54,10 @@ export async function handleTestAttestationRequest(
       key,
       testRequest.phoneNumber,
       testRequest.message,
-      null,
+      '12345678',
       testRequest.message,
+      undefined,
+      undefined,
       logger,
       sequelizeLogger,
       testRequest.provider

packages/attestation-service/src/sms/index.ts

@@ -203,6 +203,8 @@ export async function startSendSms(
   messageToSend: string,
   securityCode: string | null = null,
   attestationCode: string | null = null,
+  appSignature: string | undefined,
+  language: string | undefined,
   logger: Logger,
   sequelizeLogger: SequelizeLogger,
   onlyUseProvider: string | null = null
@@ -243,6 +245,8 @@ export async function startSendSms(
         ongoingDeliveryId: null,
         securityCode,
         securityCodeAttempt: 0,
+        appSignature,
+        language,
       },
       transaction
     )
@@ -285,6 +289,9 @@ export async function startSendSms(
 // immediately if there are sufficient attempts remaining.
 export async function rerequestAttestation(
   key: AttestationKey,
+  appSignature: string | undefined,
+  language: string | undefined,
+  securityCodePrefix: string,
   logger: Logger,
   sequelizeLogger: SequelizeLogger
 ): Promise<AttestationModel> {
@@ -301,6 +308,18 @@ export async function rerequestAttestation(
     if (!attestation) {
       throw new Error('Cannot retrieve attestation')
     }
+    // For backward compatibility
+    // Can be removed after 1.3.0
+    if (!attestation.appSignature) {
+      attestation.appSignature = appSignature
+    }
+    if (!attestation.language) {
+      attestation.language = language
+    }
+    // Old security code approach did not store the prefix
+    if (attestation.securityCode?.length === 7) {
+      attestation.securityCode = `${securityCodePrefix}${attestation.securityCode}`
+    }
 
     if (attestation.completedAt) {
       const completedAgo = Date.now() - attestation.completedAt!.getTime()

packages/attestation-service/src/sms/twilio.ts

@@ -2,7 +2,7 @@ import bodyParser from 'body-parser'
 import Logger from 'bunyan'
 import express from 'express'
 import twilio, { Twilio } from 'twilio'
-import { fetchEnv } from '../env'
+import { fetchEnv, fetchEnvOrDefault } from '../env'
 import { AttestationModel, AttestationStatus } from '../models/attestation'
 import { readUnsupportedRegionsFromEnv, SmsProvider, SmsProviderType } from './base'
 import { receivedDeliveryReport } from './index'
@@ -12,25 +12,68 @@ export class TwilioSmsProvider extends SmsProvider {
     return new TwilioSmsProvider(
       fetchEnv('TWILIO_ACCOUNT_SID'),
       fetchEnv('TWILIO_MESSAGING_SERVICE_SID'),
+      fetchEnvOrDefault('TWILIO_VERIFY_SERVICE_SID', ''),
       fetchEnv('TWILIO_AUTH_TOKEN'),
       readUnsupportedRegionsFromEnv('TWILIO_UNSUPPORTED_REGIONS', 'TWILIO_BLACKLIST')
     )
   }
 
   client: Twilio
   messagingServiceSid: string
+  verifyServiceSid: string
   type = SmsProviderType.TWILIO
   deliveryStatusURL: string | undefined
+  // https://www.twilio.com/docs/verify/api/verification#start-new-verification
+  twilioSupportedLocales = [
+    'af',
+    'ar',
+    'ca',
+    'cs',
+    'da',
+    'de',
+    'el',
+    'en',
+    'en-gb',
+    'es',
+    'fi',
+    'fr',
+    'he',
+    'hi',
+    'hr',
+    'hu',
+    'id',
+    'it',
+    'ja',
+    'ko',
+    'ms',
+    'nb',
+    'nl',
+    'pl',
+    'pt',
+    'pr-br',
+    'ro',
+    'ru',
+    'sv',
+    'th',
+    'tl',
+    'tr',
+    'vi',
+    'zh',
+    'zh-cn',
+    'zh-hk',
+  ]
 
   constructor(
     twilioSid: string,
     messagingServiceSid: string,
+    verifyServiceSid: string,
     twilioAuthToken: string,
     unsupportedRegionCodes: string[]
   ) {
     super()
     this.client = twilio(twilioSid, twilioAuthToken)
     this.messagingServiceSid = messagingServiceSid
+    this.verifyServiceSid = verifyServiceSid
     this.unsupportedRegionCodes = unsupportedRegionCodes
   }
 
@@ -76,15 +119,76 @@ export class TwilioSmsProvider extends SmsProvider {
     } catch (error) {
       throw new Error(`Twilio Messaging Service could not be fetched: ${error}`)
     }
+    if (this.verifyServiceSid) {
+      try {
+        await this.client.verify.services
+          .get(this.verifyServiceSid)
+          .fetch()
+          .then((service) => {
+            if (!service.customCodeEnabled) {
+              // Make sure that custom code is enabled
+              throw new Error(
+                'TWILIO_VERIFY_SERVICE_SID is specified, but customCode is not enabled. Please contact Twilio support to enable it.'
+              )
+            }
+          })
+      } catch (error) {
+        throw new Error(`Twilio Verify Service could not be fetched: ${error}`)
+      }
+    }
   }
 
   async sendSms(attestation: AttestationModel) {
-    const m = await this.client.messages.create({
-      body: attestation.message,
-      to: attestation.phoneNumber,
-      from: this.messagingServiceSid,
-      statusCallback: this.deliveryStatusURL,
-    })
-    return m.sid
+    // Prefer Verify API if Verify Service is present
+    if (this.verifyServiceSid) {
+      const requestParams: any = {
+        to: attestation.phoneNumber,
+        channel: 'sms',
+        customCode: attestation.securityCode,
+      }
+
+      // This param tells Twilio to add the <#> prefix and app hash postfix
+      if (attestation.appSignature) {
+        requestParams.appHash = attestation.appSignature
+      }
+      // Normalize to locales that Twilio supports
+      // If locale is not supported, Twilio API will throw an error
+      if (attestation.language) {
+        const locale = attestation.language.toLocaleLowerCase()
+        if (['es-419', 'es-us', 'es-la'].includes(locale)) {
+          attestation.language = 'es'
+        }
+        if (this.twilioSupportedLocales.includes(locale)) {
+          requestParams.locale = locale
+        }
+      }
+      try {
+        const m = await this.client.verify
+          .services(this.verifyServiceSid)
+          .verifications.create(requestParams)
+        return m.sid
+      } catch (e) {
+        // Verify landlines using voice
+        if (e.message.includes('SMS is not supported by landline phone number')) {
+          requestParams.appHash = undefined
+          requestParams.channel = 'call'
+          const m = await this.client.verify
+            .services(this.verifyServiceSid)
+            .verifications.create(requestParams)
+          return m.sid
+        } else {
+          throw e
+        }
+      }
+    } else {
+      // Send using the message service
+      const m = await this.client.messages.create({
+        body: attestation.message,
+        to: attestation.phoneNumber,
+        from: this.messagingServiceSid,
+        statusCallback: this.deliveryStatusURL,
+      })
+      return m.sid
+    }
   }
 }