ivr-lambdas

ivr-lambdas Contains the AWS Lambda functions of the Sequent Telephone Voting System.

Note: This code is a MVP initially developed for a client that required telephone voting. Currently it's not a generic system, and needs to be manually configured for each election.

Design

The IVR is just a wrapper around Sequent Voting Platform. It uses AWS Connect to generate a simple IVR system for telephone voting, and requires the following two AWS lambda functions with the Sequent backend API to work:

1. authenticate_voter lambda, that receives the credentials that the voter provided telephonically and authenticates it, returning the bearer token credential. This token will be stored in a contact attribute to be used later when casting the vote.
2. record_vote lambda, that receives the intention of the vote that the voter recorded using the telephone together with the bearer token credential obtained from the previous call to the authenticate_voter lambda, and then encrypts the vote and sends it to the ballot box.

Development environment

ivr-lambdas uses Github dev containers to facilitate development. To start developing ivr-lambdas, clone the github repo locally, and open the folder in Visual Studio Code in a container. This will configure the same environment that ivr-lambdas developers use, including installing required packages and VS Code plugins.

We've tested this dev container for Linux x86_64 and Mac Os arch64 architectures. Unfortunately at the moment it doesn't work with Github Codespaces as nix doesn't work on Github Codespaces yet. Also the current dev container configuration for ivr-lambdas doesn't allow commiting to the git repo from the dev container, you should use git on a local terminal.

Building

ivr-lambdas uses the Nix Package Manager as its package builder. To build ivr-lambdas, first install Nix correctly in your system (the dev container already does this). If you're running the project on a dev container, you shouldn't need to install it.

After you have installed Nix, enter the development environment with:

nix develop

You can build the lambdas for deployment using cargo-lambda as mentioned in the Rust runtime for AWS Lambda:

cargo lambda build --release --arm64

Testing lambdas locally

You can test the lambda functions locally. For example, you can run the authenticate_voter lambda by executing in one terminal:

export LOGIN_URL=test_url
export USER_ID_KEY=user_id_key
export VOTER_PIN_KEY=voter_pin_key
cargo lambda watch -v --print-traces -- -C authenticate_voter

And then in another terminal:

cargo lambda invoke --data-file authenticate_voter/test/test_data_1.json

Note that:

1. Because of the limitations of the interaction of cargo-watch and cargo workspaces, the lambda will be rebuild in the first invocation of the lambda.
2. This is just an example of how to invoke the lambda, but this example will fail as it requires the proper configuration of the lambda environment variables.

Running unit tests

You can run unit tests with:

cargo test

Lambda Deployment

Deployment of the lambdas can be performed manually using cargo-lambda. For reference, please review the documentation of the cargo lambda deploy command.

In the deployment-skel directory you have a script deploy.sh that you can use as a base for deployment. It's designed so that you copy the directory to deploy/ with cp -r deployment-skel deployment and then change the configuration in that file and the others in the directory to adapt to the specifics of your deployment.

Once that is done, you will be able to deploy the IVR lambda functions by simply executing:

./deployment/deploy.sh

Connecting to Sequent Telephone Voting in AWS Connect

The purpose of these lambda functions is to be used as part of Sequent Telephone Voting Platform. The AWS Connect "Sequent Telephone Voting" Contact Flow includes calls to the lambda functions. However, for that to work it's required that:

1. The lambda functions are deployed in the same region as the AWS Contact Flow.
2. Add the lambda functions to the AWS Connect instance.

Debugging

Once deployed, AWS Lambda function logs are stored in AWS CloudWatch in the AWS Console. You can access those logs in Log Groups section. Fro example, the logs for the authenticate_voter lambda will be stored in the /aws/lambda/authenticate_voter log group.

Depending on the TRACING_LEVEL set in the env_vars used for the deployment (for example inside the deployment/authenticate_voter.env_vars file for the authenticate_voter lambda), the logs will be more or less verbose. The default level is info, and you can change it to debug to have a more verbose output.

Updating Cargo.toml

Use the following [cargo-edit] command to upgrade dependencies to latest available version. This can be done within the nix develop environment:

cargo upgrade -Z preserve-precision

This repository doesn´t include a Cargo.lock file as it is intended to work as a library. However for Wasm tests we keep a copy of the file on Cargo.lock.copy. If you update Cargo.toml, keep the lock copy file in sync by generating the lock file with cargo generate-lockfile, then mv Cargo.lock Cargo.lock.copy and commit the changes.