From 9e7100bf3545eeed5270974286d57382525ea412 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Wed, 20 Dec 2023 12:49:46 +0100 Subject: [PATCH 1/9] readme for the bulletin_board api client --- bulletin_board/ruby-client/README.md | 34 ++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/bulletin_board/ruby-client/README.md b/bulletin_board/ruby-client/README.md index f79fc683..7121b1c4 100644 --- a/bulletin_board/ruby-client/README.md +++ b/bulletin_board/ruby-client/README.md @@ -1,15 +1,16 @@ # Decidim::BulletinBoard -Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/decidim/bulletin_board`. To experiment with that code, run `bin/console` for an interactive prompt. +The Bulletin Board is a service composed by an Encryption Engine and an Append-Only Log. External queries to the Encryption Engine are allowed through a GraphQL API (see https://github.com/decidim/decidim-bulletin-board). + +This gem provides a collection of commands to interact with such API using Ruby. Mainly for it's use in a backend service. -TODO: Delete this and the text above, and describe your gem ## Installation Add this line to your application's Gemfile: ```ruby -gem 'decidim-bulletin_board' +gem 'decidim-bulletin_board', "~> 0.24.4" ``` And then execute: @@ -22,13 +23,32 @@ Or install it yourself as: ## Usage -TODO: Write usage instructions here +Basic usage involves creating a client and using it to perform the desired operations: + +```ruby +# Instantiate a client +bulletin_board = Decidim::BulletinBoard::Client.new + +# Perform operations +bulletin_board.cast_vote(election_id, voter_id, encrypted_data) do |message_id| + # Do something else with the message_id +end +``` + +See a list of available operations here: https://github.com/decidim/decidim-bulletin-board/blob/develop/bulletin_board/ruby-client/lib/decidim/bulletin_board/client.rb + + +This module is used by the module Decidim Elections, check it out here: + +- https://github.com/decidim/decidim/tree/develop/decidim-elections -## Development +Usage examples: -After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. +- https://github.com/decidim/decidim/blob/develop/decidim-elections/lib/decidim/elections.rb +- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/commands/decidim/elections/voter/cast_vote.rb +- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/commands/decidim/elections/voter/update_vote_status.rb +- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/commands/decidim/elections/admin/setup_election.rb -To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). ## Contributing From a916515f04e579732ed635ad0947b443865387c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Wed, 20 Dec 2023 12:58:54 +0100 Subject: [PATCH 2/9] complete server readme --- bulletin_board/server/README.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/bulletin_board/server/README.md b/bulletin_board/server/README.md index ba046b57..e5bcb828 100644 --- a/bulletin_board/server/README.md +++ b/bulletin_board/server/README.md @@ -9,41 +9,53 @@ The Bulletin Board is a service composed by an Encryption Engine and an Append-O - System dependencies: - Python gmpy2 package dependencies: libgmp, libmpfr and libmpc -The Bulletin Board depends on the existence of a Decidim installation. +The Bulletin Board is intended to use alongside a Decidim installation. It's main purpose is to provide a GraphQL interface to a secure, auditable and verifiable voting system. This is currently achieved by using the [ElectionGuard python implementation](https://github.com/microsoft/electionguard-python), developed by Microsoft. So this server acts as a wrapper to the ElectionGuard python code. -- Installation: +Please check the [main documentation](../../README.adoc) for this repository for more convenient ways to run the Bulletin Board. + +## Installation: First, clone the repository and enter in the new folder: -``` +```bash git clone git@github.com:decidim/decidim-bulletin-board.git cd decidim-bulletin-board/server ``` Now, execute these commands: -``` +```bash bundle install npm install rails db:create rails db:migrate ``` -- How to run the rubocop linter +## Run the server +```bash +bin/rails server ``` + +Conect to the GraphQL interface in http://localhost:3000/api (documentation is embedded) + +## other commands + +- How to run the rubocop linter + +```bash bundle exec rubocop ``` - How to run the test suite -``` +```bash bundle exec rspec ``` - How to update the GraphQL schema definition run: -``` +```bash bundle exec rake schema:generate npm run schema:generate ``` From 528e147596ee59ca20d66706f794759b6687bc46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Wed, 20 Dec 2023 13:26:09 +0100 Subject: [PATCH 3/9] voting schemes readmes --- bulletin_board/server/README.md | 6 +++++- voting_schemes/dummy/ruby-adapter/README.md | 14 ++++++-------- .../electionguard/ruby-adapter/README.md | 19 +++++++++++-------- 3 files changed, 22 insertions(+), 17 deletions(-) diff --git a/bulletin_board/server/README.md b/bulletin_board/server/README.md index e5bcb828..a9f83464 100644 --- a/bulletin_board/server/README.md +++ b/bulletin_board/server/README.md @@ -9,7 +9,11 @@ The Bulletin Board is a service composed by an Encryption Engine and an Append-O - System dependencies: - Python gmpy2 package dependencies: libgmp, libmpfr and libmpc -The Bulletin Board is intended to use alongside a Decidim installation. It's main purpose is to provide a GraphQL interface to a secure, auditable and verifiable voting system. This is currently achieved by using the [ElectionGuard python implementation](https://github.com/microsoft/electionguard-python), developed by Microsoft. So this server acts as a wrapper to the ElectionGuard python code. +The Bulletin Board is intended to use alongside a Decidim installation. It's main purpose is to provide a GraphQL interface to a secure, auditable and verifiable voting system. This is currently achieved by using the [ElectionGuard python implementation](https://github.com/microsoft/electionguard-python), developed by Microsoft. So this server acts as a [wrapper to the ElectionGuard python code](../../voting_schemes/electionguard/python-wrapper). + +See how python code is executed using PyCall here: +- https://github.com/decidim/decidim-bulletin-board/blob/develop/bulletin_board/server/app/services/voting_scheme/electionguard/voter.rb +- https://github.com/decidim/decidim-bulletin-board/blob/develop/bulletin_board/server/app/services/voting_scheme/electionguard/bulletin_board.rb Please check the [main documentation](../../README.adoc) for this repository for more convenient ways to run the Bulletin Board. diff --git a/voting_schemes/dummy/ruby-adapter/README.md b/voting_schemes/dummy/ruby-adapter/README.md index 28738422..18d66201 100644 --- a/voting_schemes/dummy/ruby-adapter/README.md +++ b/voting_schemes/dummy/ruby-adapter/README.md @@ -1,8 +1,6 @@ # VotingSchemes::Dummy -Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/voting_schemes/dummy`. To experiment with that code, run `bin/console` for an interactive prompt. - -TODO: Delete this and the text above, and describe your gem +The Bulletin Board is a generic API for storing and retrieving ballots and tallies for elections. The final implementation of the protocol used for creating an election may vary. This gem provides a dummy implementation for testing purposes. ## Installation @@ -22,14 +20,14 @@ Or install it yourself as: ## Usage -TODO: Write usage instructions here +This implementation is intended for testing purposes only. It allows to test the Bulletin Board without the need to use a fully configured Decidim installation. +It also skips the encryption and decryption steps, so it is not suitable for production use. -## Development +You can [start the server](../../bulletin_board/server) in development mode and connect to the built-in testing admin sandbox at: -After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. +http://localhost:3000/sandbox -To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org). ## Contributing -Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/voting_schemes-dummy. +Bug reports and pull requests are welcome on GitHub at https://github.com/decidim/decidim-bulletin-board/issues. diff --git a/voting_schemes/electionguard/ruby-adapter/README.md b/voting_schemes/electionguard/ruby-adapter/README.md index 92985a5e..bb6ee9d0 100644 --- a/voting_schemes/electionguard/ruby-adapter/README.md +++ b/voting_schemes/electionguard/ruby-adapter/README.md @@ -1,8 +1,13 @@ # VotingSchemes::Electionguard -Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/voting_schemes/electionguard`. To experiment with that code, run `bin/console` for an interactive prompt. +The Bulletin Board is a generic API for storing and retrieving ballots and tallies for elections. The final implementation of the protocol used for creating an election may vary. This gem provides the [Microsoft's ElectionGuard](https://github.com/microsoft/electionguard-python) Javascript implementation for production use in Decidim. -TODO: Delete this and the text above, and describe your gem +Note that the ElectionGuard implementation works by using two different wrappers around Electionguard: + +- A [Python Wrapper](../python-wrapper) for its use in the backend of the [GraphQL API server](../../../bulletin_board/server). +- A [Javascript Wrapper](../js-adapter) that compiles the whole Electionguard python app into web-assembly and allows to use it in the frontend (this ensure that the voting process is not tampered by sending any data to the backend). + +This gem provides a very simple gem that wraps the Javascript implementation and allows to use it in the frontend of a Decidim application (Elections module). ## Installation @@ -22,14 +27,12 @@ Or install it yourself as: ## Usage -TODO: Write usage instructions here - -## Development +You can see examples of usage by looking at the Decidim Elections module: -After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. +- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/packs/src/decidim/elections/voter/casting-vote.js +- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/packs/src/decidim/elections/election_log.js -To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org). ## Contributing -Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/voting_schemes-electionguard. +Bug reports and pull requests are welcome on GitHub at https://github.com/decidim/decidim-bulletin-board. From 1d9654c61604228cc47bce41b92473f7bb91cee7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Tue, 9 Jan 2024 14:05:29 +0100 Subject: [PATCH 4/9] fix typos --- bulletin_board/ruby-client/README.md | 16 +++++++++------- bulletin_board/server/README.md | 2 +- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/bulletin_board/ruby-client/README.md b/bulletin_board/ruby-client/README.md index 7121b1c4..42e30044 100644 --- a/bulletin_board/ruby-client/README.md +++ b/bulletin_board/ruby-client/README.md @@ -4,22 +4,25 @@ The Bulletin Board is a service composed by an Encryption Engine and an Append-O This gem provides a collection of commands to interact with such API using Ruby. Mainly for it's use in a backend service. - ## Installation -Add this line to your application's Gemfile: +Run this command to add the gem to your Gemfile: -```ruby -gem 'decidim-bulletin_board', "~> 0.24.4" +```console +bundle add decidim-bulletin_board ``` And then execute: - $ bundle install +```console +bundle install +``` Or install it yourself as: - $ gem install decidim-bulletin_board +```console +gem install decidim-bulletin_board +``` ## Usage @@ -37,7 +40,6 @@ end See a list of available operations here: https://github.com/decidim/decidim-bulletin-board/blob/develop/bulletin_board/ruby-client/lib/decidim/bulletin_board/client.rb - This module is used by the module Decidim Elections, check it out here: - https://github.com/decidim/decidim/tree/develop/decidim-elections diff --git a/bulletin_board/server/README.md b/bulletin_board/server/README.md index a9f83464..cf136ced 100644 --- a/bulletin_board/server/README.md +++ b/bulletin_board/server/README.md @@ -9,7 +9,7 @@ The Bulletin Board is a service composed by an Encryption Engine and an Append-O - System dependencies: - Python gmpy2 package dependencies: libgmp, libmpfr and libmpc -The Bulletin Board is intended to use alongside a Decidim installation. It's main purpose is to provide a GraphQL interface to a secure, auditable and verifiable voting system. This is currently achieved by using the [ElectionGuard python implementation](https://github.com/microsoft/electionguard-python), developed by Microsoft. So this server acts as a [wrapper to the ElectionGuard python code](../../voting_schemes/electionguard/python-wrapper). +The Bulletin Board is intended to use alongside a Decidim installation. Its main purpose is to provide a GraphQL interface to a secure, auditable and verifiable voting system. This is currently achieved by using the [ElectionGuard python implementation](https://github.com/microsoft/electionguard-python), developed by Microsoft. So this server acts as a [wrapper to the ElectionGuard python code](../../voting_schemes/electionguard/python-wrapper). See how python code is executed using PyCall here: - https://github.com/decidim/decidim-bulletin-board/blob/develop/bulletin_board/server/app/services/voting_scheme/electionguard/voter.rb From 20a2c9d3eade227c5ee873a1a908bdebcf86e781 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Thu, 11 Jan 2024 15:12:55 +0100 Subject: [PATCH 5/9] Update bulletin_board/ruby-client/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Andrés Pereira de Lucena --- bulletin_board/ruby-client/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/bulletin_board/ruby-client/README.md b/bulletin_board/ruby-client/README.md index 42e30044..cfeac728 100644 --- a/bulletin_board/ruby-client/README.md +++ b/bulletin_board/ruby-client/README.md @@ -12,7 +12,6 @@ Run this command to add the gem to your Gemfile: bundle add decidim-bulletin_board ``` -And then execute: ```console bundle install From a6e97903ef8a7e68154451e319d2bfe510a5d33d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Thu, 11 Jan 2024 15:13:01 +0100 Subject: [PATCH 6/9] Update bulletin_board/ruby-client/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Andrés Pereira de Lucena --- bulletin_board/ruby-client/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/bulletin_board/ruby-client/README.md b/bulletin_board/ruby-client/README.md index cfeac728..86f48ea4 100644 --- a/bulletin_board/ruby-client/README.md +++ b/bulletin_board/ruby-client/README.md @@ -12,7 +12,6 @@ Run this command to add the gem to your Gemfile: bundle add decidim-bulletin_board ``` - ```console bundle install ``` From faebaefe536ea8ff5f3ad8ad3ab0716d0055fb7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Thu, 11 Jan 2024 15:13:07 +0100 Subject: [PATCH 7/9] Update bulletin_board/ruby-client/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Andrés Pereira de Lucena --- bulletin_board/ruby-client/README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/bulletin_board/ruby-client/README.md b/bulletin_board/ruby-client/README.md index 86f48ea4..14e9427e 100644 --- a/bulletin_board/ruby-client/README.md +++ b/bulletin_board/ruby-client/README.md @@ -12,9 +12,6 @@ Run this command to add the gem to your Gemfile: bundle add decidim-bulletin_board ``` -```console -bundle install -``` Or install it yourself as: From 90c1e7f709379f82618d5ec2f31fe6c3bfdd37a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Thu, 11 Jan 2024 15:13:14 +0100 Subject: [PATCH 8/9] Update bulletin_board/ruby-client/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Andrés Pereira de Lucena --- bulletin_board/ruby-client/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/bulletin_board/ruby-client/README.md b/bulletin_board/ruby-client/README.md index 14e9427e..4f22b5b7 100644 --- a/bulletin_board/ruby-client/README.md +++ b/bulletin_board/ruby-client/README.md @@ -12,7 +12,6 @@ Run this command to add the gem to your Gemfile: bundle add decidim-bulletin_board ``` - Or install it yourself as: ```console From 38a8f4d2538a83b6c5eeba04c8082016f9497e7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Thu, 11 Jan 2024 15:13:21 +0100 Subject: [PATCH 9/9] Update bulletin_board/ruby-client/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Andrés Pereira de Lucena --- bulletin_board/ruby-client/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bulletin_board/ruby-client/README.md b/bulletin_board/ruby-client/README.md index 4f22b5b7..60ae60f9 100644 --- a/bulletin_board/ruby-client/README.md +++ b/bulletin_board/ruby-client/README.md @@ -2,7 +2,7 @@ The Bulletin Board is a service composed by an Encryption Engine and an Append-Only Log. External queries to the Encryption Engine are allowed through a GraphQL API (see https://github.com/decidim/decidim-bulletin-board). -This gem provides a collection of commands to interact with such API using Ruby. Mainly for it's use in a backend service. +This gem provides a collection of commands to interact with such API using Ruby, mainly for its use in a backend service. ## Installation