Skip to content

Latest commit

 

History

History
 
 

attestation-service

README.md

Attestation Service

A service run by validators on the Celo network to send SMS messages, enabling attestations of user phone numbers and their accounts on the Celo network.

Configuration

You can use the following environment variables to configure the attestation service:

  • DATABASE_URL - The URL under which your database is accessible, currently supported are postgres://, mysql:// and sqlite://
  • CELO_PROVIDER - The URL under which a celo blockchain node is reachable. This node should also have the ATTESTATION_SIGNER_ADDRESS unlocked for signing of the attestations themselves.
  • CELO_VALIDATOR_ADDRESS - The address of the validator on the Accounts smart contract
  • ATTESTATION_SIGNER_ADDRESS - The address of the key with which attestations should be signed.
  • SMS_PROVIDERS - A comma-separated list of providers you want to configure, we currently support:

nexmo

  • NEXMO_KEY - The API key to the Nexmo API
  • NEXMO_SECRET - The API secret to the Nexmo API
  • NEXMO_BLACKLIST - A comma-sperated list of country codes you do not want to serve

twilio

  • TWILIO_ACCOUNT_SID - The SID of your Twilio account
  • TWILIO_MESSAGE_SERVICE_SID - The SID of the messaging service you want to use. The messaging service should have at least 1 phone number associated with it.
  • TWILIO_AUTH_TOKEN - The auth token for your Twilio account

Operations

This service uses bunyan for structured logging with JSON lines. You can pipe STDOUT to yarn run bunyan for a more human friendly output. The LOG_LEVEL environment variable can specify desired log levels. We support the following LOG_FORMATs:

  • Default are json lines LOG_FORMAT=json
  • With LOG_FORMAT=stackdriver you can get stackdriver specific format to recover information such as error traces etc.
  • To get something more human readable, use LOG_FORMAT=human

This service exposes prometheus metrics under /metrics.

Running locally

After checking out the source, you should create a local sqlite database by running:

yarn run db:create:dev
yarn run db:migrate:dev

You will also have to set the environment variables in .env.development

Then start the service with yarn run dev (you'll have to add the appropriate credentials for the text providers)

Error Responses

Here is a list of the error codes and messages returned by the Attestation Service and what they mean. In addition to the error codes listed below, the service also returns 500 for Unknown Error.

422, Unprocessable Entity

  • Mismatching issuer, I am ${address} - The attestation request references an issuer address that does not match that of the AS that actually received the request.
  • NO_INCOMPLETE_ATTESTATION_FOUND_ERROR / 'No incomplete attestation found' - The Attestations contract has no record that this AS was randomly assigned as an issuer for the given account/identifier pair.
  • ATTESTATION_ERROR / 'Valid attestation could not be provided' - A call to validateAttestationCode in the Attestations contract has failed. This method checks that (1) there is a non-expired incomplete attestation assigned to the issuer whose signature constitutes the given attestation code.
  • 'Invalid securityCodePrefix' - A security code prefix with an incorrect length was provided in the attestation request.
  • 'Invalid smsRetrieverAppSig' - The provided smsRetrieverAppSig does not match the regex '^[\\w+]{5,12}$'
  • 'Attestation can no longer be re-requested' - The user is re-requesting an attestation that the AS thinks was completed too long ago for it to accept the re-request.
  • 'Delivery attempts exceeded' - The AS has attempted to deliver this attestation to the user too many times and will not try again.
  • ErrorMessages.NO_PROVIDER_SETUP / 'No provider was setup for this phone number' - The AS has not setup an SMS provider
  • ErrorMessages.INVALID_SIGNATURE / 'Invalid signature provided' - The signature provided in a AttestationServiceTestRequest was not generated by either the AS's account address or attestation signer address.

404, Not Found

  • 'Attestation not found' - The attestation the user is attempting to complete could not be found in the AS's database.

403, Forbidden

  • 'Security code attempts exceeded' - The user has attempted to complete the attestation with an incorrect security code too many times. The attestation can no longer be completed.
  • 'Invalid security code' - The user has attempted to complete the attestation with an incorrect security code.

401, Unauthorized

  • 'Missing authentication' - the authentication header is missing from the request
  • 'Invalid signature' - The authentication header failed signature verification. It should be signed by either the account's DEK or wallet key.