🗳 ElectionGuard Typescript

A TypeScript library that implements a subset of the ElectionGuard spec, allowing encryption of ballots in browsers or other JavaScript engines.

Features

Ballot encryption and JSON serialization

We support a synchronous API, where we encrypt a PlaintextBallot object and return a CiphertextBallot object. We also support an asynchronous API, where PlaintextContest objects are encrypted asynchronously, and a CiphertextBallot can be fetched at the end. This allows the ballot encryption process to be spread across a voting session, minimizing user-visible lag.

Note: write-ins and overvotes are not supported in our implementation of ElectionGuard 1.0.
Compatibility with electionguard-python

Ciphertext ballots created by ElectionGuard Typescript will match those created by electionguard-python. Additionally, elections and ballots generated by electionguard-python can be used with ElectionGuard Typescript.
Support for modern browsers (roughly since 2018) including bigint support
Support for NodeJS

Note: While the package @electionguard/api-client is a Typescript interface for frontends that want to communicate with a server that implements the ElectionGuard specification, this package is an implementation of (a subset of) the ElectionGuard spec.

Non-features

Ballot decryption
Ballot or election verification

Installation

Node

npm install electionguard
# or
yarn add electionguard

Browser

As an ES module:

<head>
  <!-- ... -->
  <script type="module">
    import {ManifestParty, bigIntContext4096} from './dist/electionguard.js';
    console.log(new ManifestParty(bigIntContext4096(), 'example'));
  </script>
</head>

As a UMD module:

<head>
  <!-- ... -->
  <script src="https://github.com/danwallach/ElectionGuard-TypeScript/raw/main/dist/electionguard.umd.js"></script>
</head>
<body>
  <!-- ... -->
  <script>
    console.log(
      new eg.ManifestParty(eg.bigIntContext4096(), 'example')
    );
  </script>
</body>

Usage

import {
  AsyncBallotEncryptor,
  bigIntContext4096,
  EncryptionDevice,
  PlaintextBallot,
  PlaintextContest,
  PlaintextSelection,
} from 'electionguard';

// computational context for subsequent encryptions
const context = bigIntContext4096();

// specification of the "device" computing the encryptions
const device = new EncryptionDevice(context, 55890250559315, 12345, 45678, 'polling-place');
let codeSeed = device.cryptoHashElement;

// data structures that would normally be downloaded alongside an election definition
const manifestObj = {
  election_scope_id: 'hamilton-county-general-election',
  spec_version: '1.0',
  // ...
};
const electionContextObj = {
  number_of_guardians: 5,
  quorum: 3,
  // ...
};

// data structures representing an unencrypted ballot
const ballot = new PlaintextBallot(
  'ballot-8a27eaa6-f1c3-11ec-b605-aaf53b701db4',
  'congress-district-5-hamilton-county',
  [
    new PlaintextContest('president-vice-president-contest', [
      new PlaintextSelection('cramer-vuocolo-selection', 1),
    ]),
    // ...
  ]
);

// asynchronous API for encrypting each contest as the user specifies it
const encryptor = AsyncBallotEncryptor.create(
  context,
  manifestObj,
  electionContextObj,
  false,
  ballot.ballotStyleId,
  ballot.ballotId,
  codeSeed
);
ballot.contests.forEach(contest => encryptor.encrypt(contest));

(async () => {
  // collect the encrypted ballot, blocking until all encryption is complete
  const result = await encryptor.getSerializedEncryptedBallot();

  const {serializedEncryptedBallot, ballotHash, ballotSeed} = result;
  // - serializedEncryptedBallot is a plain JavaScript object, suitable
  //   for converting to JSON, with the encrypted ballot.

  // - ballotHash is a bigint, representing the hash of the encrypted
  //   ballot, which a voter could potentially keep as their "receipt"

  // - ballotSeed is a bigint, representing the source of the randomness
  //   used to encrypt the ballot. This is a sensitive value that
  //   might be printed on the bottom of a human-readable paper ballot
  //   to allow a remote system to exactly recompute the encrypted ballot.

  console.log(JSON.stringify(serializedEncryptedBallot, null, 2));
})();

See the examples directory for more examples.

Check the documentation for a full list of exports.

Documentation

You can generate API documentation using TypeDoc.

npm run docs

Development

# Install dependencies
npm install

# Now you can run various npm commands:
npm run test
npm run coverage
npm run build
npm run elgamal-bench
# ...

# Auto-indenter and linter (uses gts)
npm run fix

To try the browser examples, run npm run build first.

To run the node examples, first run npm pack in the root directory and uncompress the generated .tgz file.

License

MIT License

Authors

Han Guo alexiland@outlook.com
Xin Hao xinhaofighting@gmail.com
Shreyas Minocha shreyasminocha@rice.edu
Dan S. Wallach dwallach@rice.edu or dwallach@gmail.com
Arthur Wu wuwenqin200613@gmail.com
Yanyu Zhong yanyuzhongzyy@gmail.com
Zihe Zhao zz83@rice.edu

danwallach / ElectionGuard-TypeScript

readme