juvenal-lib: The universal election verifier library

• API Documentation: https://nvotes.github.io/juvenal-lib
• Web interface repo: https://github.com/nvotes/juvenal
• Web interface demo: https://nvotes.github.io/juvenal

juvenal-lib is a library that implements an universal election verifier. It enables the verification of election ballots, tallies, and proofs generated by multiple voting solutions. It has been developed independently by the nVotes Online Voting team and is written in TypeScript. It also includes a command line verifier.

It currently only supports verifying ElectionGuard. Work for supporting Helios Voting is in the works. This library is used by Juvenal, which is an open-source and web-based universal verifier.

WARNING: This software is in development and is incomplete and most probably contains bugs. Please do not use in production.

Building

This is a TypeScript project and uses the standard TypeScript toolchain. Install dependencies with:

yarn

Then you can build the project into javascript to the build/ directory with:

yarn build

You can execute the unit tests with:

yarn test

You can generate package documentation with:

yarn doc

Running

You can run the verifier through the command line using node:

node build/src/bin/verifier.js $PATH_TO_ELECTION_RECORD.json

There are multiple election record examples in the directory test/data that you can use with the verifier. For example, the following command should verify correctly the valid_encrypted.json election record, which contains a valid election record:

node build/src/bin/verifier.js tests/data/valid_encrypted.json

Contribute

There are multiple ways to contribute:

• Submit bugs and help us verify fixes as they are checked in.
• Create Pull Requests implementing new features.
• Create Pull Requests implementing proofs verification for a verifiable voting system not yet supported.
• Review source code changes.
• Use the discord channel to engage with the community.

Security dependencies update

You can run yarn audit to find security dependencies that need to be updated. You can also run yarn run yarn-audit-fix to try to update the dependencies to a secure version. Afterwards, you should try to do a yarn build and yarn test to ensure everything is still working.

Development

Note that we autogenerate both:

• The file json_schemas.ts (in directory vendor/electionguard-schema-0.85) that contains the schemas as an object, so that they can be directly loaded as a javascript dependency and not opening json files.
• The schema definitions in directory vendor/electionguard-schema-0.85/@types, so that the election record to be verified can be loaded from json in a typed manner.

When required, you can update the two generated json schemas derivatives mentioned above by running:

yarn generate_election_record_types

Dependencies

The verifier uses minimal runtime dependencies to be very self-contained:

• verificatum-vjsc: Self-contained javascript cryptographic library for use in electronic voting clients. Developed and maintained by Douglas Wikström and part of the Verificatum project. It's directly included in the vendors directory.
• ajv: A JSON Schema draft-07 validator, as the verifiable data is in JSON and the ElectionGuard Specification includes the JSON Schema of the election record. We have directly extracted and copied verbatim these schemas in the vendors directory.

There is a bunch of other development-only additional dependencies. These are not really relevant other than for development purposes:

• jest: TypeScript-friendy testing framework.
• typedoc: Generates package documentation.
• @types/node The definitions for node.js, required to process command-line arguments in the command-line verifier.
• json-schema-to-typescript: Compile json schema to TypeScript typings.
• eslint: A linting library.
• @typescript-eslint/parser: A parser that allows ESLint to lint TypeScript code.
• @typescript-eslint/eslint-plugin: A plugin that contains some ESLint rules that are TypeScript specific.
• prettier: The core prettier library.
• eslint-config-prettier: Disables ESLint rules that might conflict with prettier.
• eslint-plugin-prettier: Runs prettier as an ESLint rule.
• link-staged: Allows to run linting commands on files that are staged to be committed.
• husky: Makes git hooks simpler to use.