A TypeScript library that implements a subset of the ElectionGuard spec, allowing encryption of ballots in browsers or other JavaScript engines.
-
Ballot encryption and JSON serialization
We support a synchronous API, where we encrypt a
PlaintextBallotobject and return aCiphertextBallotobject. We also support an asynchronous API, wherePlaintextContestobjects are encrypted asynchronously, and aCiphertextBallotcan 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.
- Ballot decryption
- Ballot or election verification
npm install electionguard
# or
yarn add electionguardAs 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="./dist/electionguard.umd.js"></script>
</head>
<body>
<!-- ... -->
<script>
console.log(
new eg.ManifestParty(eg.bigIntContext4096(), 'example')
);
</script>
</body>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.
You can generate API documentation using TypeDoc.
npm run docs# 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 fixTo 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.
See also:
- 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