Skip to content

Commit c89acab

Browse files
shreyasminochashreyasminocha
committed
Update readme and package.json
1 parent e688bee commit c89acab

File tree

3 files changed

+151
-36
lines changed

3 files changed

+151
-36
lines changed

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2021 Chris Hager
3+
Copyright © 2021–2022 ElectionGuard Typescript Contributors
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md

+137-31
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,173 @@
1-
![Microsoft Defending Democracy Program: ElectionGuard Python][banner image]
1+
# 🗳 ElectionGuard Typescript
22

3-
# 🗳 ETS: ElectionGuard Typescript
3+
A typescript library that implements a subset of the [ElectionGuard](https://www.electionguard.vote/) spec to allow encryption of ballots in browsers.
44

5+
## Features
56

6-
[banner image]: https://raw.githubusercontent.com/microsoft/electionguard-python/main/images/electionguard-banner.svg
7+
- Ballot encryption
78

9+
**Note**: write-ins, overvotes, and undervotes are not supported in our implementation of ElectionGuard 1.0.
810

9-
## ❓ What Is Vote-by-mail?
10-
Vote by mail, or vote at home, is a method of voting that voters get their ballot delivered to them weeks before Election Day, fill it out at their convenience, then return it either in-person or by mail. There are two types of vote by mail system -- comprehensive vote by mail and absentee ballots. To ensure the integrity of elections and the validity of each ballot, risk-limiting audits are implemented and ballot tracking services are provided.
11+
- Compatibility with [electionguard-python](https://github.com/microsoft/electionguard-python/)
12+
- Support for [modern](https://caniuse.com/bigint) browsers
13+
- Support for NodeJS >= 14
1114

12-
## ❓ What Is End-to-End Verifiable Voting?
13-
E2E verifiable voting is a way to guarantee voting system security, preventing someone other than the sender or recipient from accessing & modifying the ballots. The voters first vote the way they would traditionally on an electronic voting system, but in the end, an e2e system would use cryptography and generate a receipt of a long numeric sequence or a qrcode. This receipt is essentially a record of the vote that's been encrypted with a secret key the voter doesn't have. But it still allows voters to verify that their votes were counted. E2E verifiable voting is able to respond to voters' challenge on whether their ballots are included by providing mathematical proofs which show that the ballots add up to the officially announced totals. That is the mechanism of how the voters can get confident evidence of their ballot being effective without revealing which candidates were voted for nor requiring them to trust election official results, software, hardware, and so on.
15+
## Non-features
1416

17+
- Ballot decryption
18+
- Verification
1519

16-
## ❓ What Is ElectionGuard?
17-
ElectionGuard is an open source software development kit (SDK) that makes voting more secure, transparent and accessible. The ElectionGuard SDK leverages homomorphic encryption to ensure that votes recorded by electronic systems of any type remain encrypted, secure, and secret. Meanwhile, ElectionGuard also allows verifiable and accurate tallying of ballots by any 3rd party organization without compromising secrecy or security.
20+
## Installation
1821

19-
## ❗️Here comes Electionguard Typescript!
20-
Our team focuses on building a bridge between the vote-by-mail system and end-to-end verifiable encryption. We want to create a user-friendly web application that not only allows user to vote and print out their ballot, but also performs chaum Peterson encryption while they are voting. This is actually an in-browser version of election guard.
22+
### Node
2123

22-
To achieve this, for Microsoft team, we built a typescript frontend implementation that uses the exactly same encryption logic as election guard. For Front end web interface, we built a fully encapsulated API to add the feature of ballot encryption for them. You can just use approximately few lines of code that calls encrpt_ballot in the front-end typescript, and we will handle everything else for you.
24+
**Note**: we haven't published a npm package yet.
2325

24-
## Workflow of ETS:
25-
Data pipeline:
26-
![workflow of ETS](README_src/workflow.png)
26+
```sh
27+
npm install github:danwallach/electionguard
28+
# or
29+
yarn add electionguard@danwallach/electionguard
30+
```
31+
32+
### Browser
33+
34+
As an **ES module**:
35+
36+
```html
37+
<head>
38+
<!-- ... -->
39+
<script type="module">
40+
import {ManifestParty, bigIntContext4096} from './dist/electionguard.js';
41+
console.log(new ManifestParty(bigIntContext4096(), 'example'));
42+
</script>
43+
</head>
44+
```
45+
46+
As a **UMD module**:
47+
48+
```html
49+
<head>
50+
<!-- ... -->
51+
<script src="./dist/electionguard.umd.js"></script>
52+
</head>
53+
<body>
54+
<!-- ... -->
55+
<script>
56+
console.log(
57+
new eg.ManifestParty(eg.bigIntContext4096(), 'example')
58+
);
59+
</script>
60+
</body>
61+
```
62+
63+
## Usage
64+
65+
```js
66+
import {
67+
AsyncBallotEncryptor,
68+
bigIntContext4096,
69+
EncryptionDevice,
70+
PlaintextBallot,
71+
PlaintextContest,
72+
PlaintextSelection,
73+
} from 'electionguard';
74+
75+
const context = bigIntContext4096();
76+
const device = new EncryptionDevice(context, 55890250559315, 12345, 45678, 'polling-place');
77+
let codeSeed = device.cryptoHashElement;
78+
79+
const manifestObj = {
80+
election_scope_id: 'hamilton-county-general-election',
81+
spec_version: '1.0',
82+
// ...
83+
};
84+
const electionContextObj = {
85+
number_of_guardians: 5,
86+
quorum: 3,
87+
// ...
88+
};
89+
const ballot = new PlaintextBallot(
90+
'ballot-8a27eaa6-f1c3-11ec-b605-aaf53b701db4',
91+
'congress-district-5-hamilton-county',
92+
[
93+
new PlaintextContest('president-vice-president-contest', [
94+
new PlaintextSelection('cramer-vuocolo-selection', 1),
95+
]),
96+
// ...
97+
]
98+
);
99+
100+
const encryptor = AsyncBallotEncryptor.create(
101+
context,
102+
manifestObj,
103+
electionContextObj,
104+
false,
105+
ballot.ballotStyleId,
106+
ballot.ballotId,
107+
codeSeed
108+
);
109+
ballot.contests.forEach(contest => encryptor.encrypt(contest));
110+
111+
(async () => {
112+
const result = await encryptor.getSerializedEncryptedBallot();
113+
const {serializedEncryptedBallot, ballotHash} = result;
114+
115+
const ballotHashModQ = context.createElementModQ(ballotHash);
116+
if (ballotHashModQ === undefined) {
117+
throw new Error('unable to create ElementModQ from ballotHash');
118+
}
119+
codeSeed = ballotHashModQ;
120+
121+
console.log(JSON.stringify(serializedEncryptedBallot, null, 2));
122+
})();
123+
```
124+
125+
<!-- See `examples/` for more examples. -->
126+
127+
Check the [documentation](#documentation) for a full list of exports.
128+
129+
## Documentation
130+
131+
<!-- TODO: deploy these somewhere -->
27132

28-
### Getting Started
133+
You can generate API documentation using [TypeDoc](https://typedoc.org/guides/doccomments/).
134+
135+
```bash
136+
npm run docs
137+
```
138+
139+
### Development
29140

30141
```bash
31142
# Install dependencies
32143
npm install
33144

34145
# Now you can run various npm commands:
35146
npm run test
147+
npm run coverage
148+
npm run build
36149
npm run elgamal-bench
37-
...
150+
# ...
38151

39152
# Auto-indenter and linter (uses gts)
40153
npm run fix
41154
```
42155

156+
See also:
43157

44-
### Documentation, published with CI
45-
46-
You can auto-generate API documentation from the TypeScript source files using [TypeDoc](https://typedoc.org/guides/doccomments/). The generated documentation can be published to GitHub / GitLab pages through the CI.
158+
- [`NOTES.md`](./NOTES.md)
159+
- [`PRECOMPUTE.md`](./PRECOMPUTE.md)
47160

48-
```bash
49-
npm run docs
50-
```
161+
## License
51162

52-
The resulting HTML is saved in `docs/`.
53-
54-
You can publish the documentation through CI:
55-
* [GitHub pages](https://pages.github.com/): See [`.github/workflows/deploy-gh-pages.yml`](https://github.com/metachris/typescript-boilerplate/blob/master/.github/workflows/deploy-gh-pages.yml)
56-
* [GitLab pages](https://docs.gitlab.com/ee/user/project/pages/): [`.gitlab-ci.yml`](https://github.com/metachris/typescript-boilerplate/blob/master/.gitlab-ci.yml)
57-
58-
This is the documentation for this boilerplate project: https://metachris.github.io/typescript-boilerplate/
163+
[MIT License](./LICENSE)
59164

60165
## Authors
166+
61167
- Han Guo <[email protected]>
62168
- Xin Hao <[email protected]>
63169
- Shreyas Minocha <[email protected]>
64170
- Dan S. Wallach <[email protected]> or <[email protected]>
65171
- Arthur Wu <[email protected]>
66172
- Yanyu Zhong <[email protected]>
67-
- Zihe Zhao <[email protected]>
173+
- Zihe Zhao <[email protected]>

‎package.json

+13-4
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,22 @@
11
{
2-
"name": "electionguard-typescript",
2+
"name": "electionguard",
33
"version": "0.6.0",
44
"description": "Client-side implementation of ElectionGuard for ballot encryption",
5-
"author": "Arthur Wu <[email protected]>",
5+
"contributors": [
6+
"Han Guo <[email protected]>",
7+
"Xin Hao <[email protected]>",
8+
"Shreyas Minocha <[email protected]>",
9+
"Dan S. Wallach <[email protected]> or <[email protected]>",
10+
"Arthur Wu <[email protected]>",
11+
"Yanyu Zhong <[email protected]>",
12+
"Zihe Zhao <[email protected]>"
13+
],
614
"repository": "https://github.com/danwallach/ElectionGuard-TypeScript",
715
"license": "MIT",
816
"keywords": [
9-
"typescript",
17+
"cryptography",
1018
"electionguard",
11-
"esbuild"
19+
"voting"
1220
],
1321
"files": [
1422
"dist",
@@ -17,6 +25,7 @@
1725
],
1826
"type": "module",
1927
"main": "dist/index.js",
28+
"module": "dist/index.js",
2029
"exports": {
2130
"import": "./dist/index.js",
2231
"require": "./dist/index.cjs",

0 commit comments

Comments
 (0)