Clarify vote receipt verification

Author: alexiri

astra_app/core/static/verify-ballot-hash.py

@@ -2,7 +2,7 @@
 """
 Verify your ballot hash (local check)
 
-Copy the values from your voting receipt into the variables below. This script
+Copy the values from your vote receipt email into the variables below. This script
 re-computes the ballot hash and compares it to the hash shown on your receipt.
 A match means the receipt details you entered produce the same hash the system recorded.
 
@@ -40,10 +40,10 @@ def compute_ballot_hash(
     return hashlib.sha256(data).hexdigest()
 
 # ===== YOUR BALLOT DETAILS =====
-# Copy/paste these values from your voting receipt and the "Verify ballot receipt" page.
+# Copy/paste these values from your vote receipt and the "Verify ballot receipt" page.
 
 election_id = 1
-credential_public_id = "your-credential-id-here"
+voting_credential = "your-credential-id-here"
 
 # Candidate IDs are what the system hashes, but voters usually think in usernames.
 # The verify page provides a complete username -> ID mapping for the election.
@@ -53,26 +53,31 @@ def compute_ballot_hash(
     "carol": 3,
 }
 
-# Your vote choices are secret. You must fill your own ranking locally.
+# Your vote choices are secret. You must fill your own ranking locally
+# as a comma-separated list of candidate usernames in your preferred order.
 # Example: if you ranked alice then bob, use:
-# ranking = [candidate_ids_by_username["alice"], candidate_ids_by_username["bob"]]
-ranking = [candidate_ids_by_username["alice"]]
+# ranking = "alice,bob"
+ranking = "alice"
 
-weight = 1  # Usually 1 (check your receipt if different)
-nonce = "your-nonce-from-receipt-email"
+weight = 1  # The weight value from your vote receipt email
+submission_nonce = "your-nonce-from-receipt-email"
 expected_ballot_hash = "your-ballot-hash-from-receipt-email"
 
+# ===== END OF USER INPUT =====
+
+ranking = [candidate_ids_by_username[x.strip()] for x in ranking.split(',')]
+
 if __name__ == "__main__":
     if not isinstance(election_id, int) or election_id <= 0:
         raise SystemExit("election_id must be a positive integer")
-    if not str(credential_public_id or "").strip():
-        raise SystemExit("credential_public_id must be set")
+    if not str(voting_credential or "").strip():
+        raise SystemExit("voting_credential must be set")
     if not isinstance(ranking, list) or not all(isinstance(cid, int) for cid in ranking):
         raise SystemExit("ranking must be a list of candidate IDs (integers)")
     if not isinstance(weight, int) or weight <= 0:
         raise SystemExit("weight must be a positive integer")
-    if not str(nonce or "").strip():
-        raise SystemExit("nonce must be set")
+    if not str(submission_nonce or "").strip():
+        raise SystemExit("submission_nonce must be set")
 
     expected = str(expected_ballot_hash or "")
     if len(expected) != 64:
@@ -86,18 +91,18 @@ def compute_ballot_hash(
 
     computed_hash = compute_ballot_hash(
         election_id=election_id,
-        credential_public_id=credential_public_id,
+        credential_public_id=voting_credential,
         ranking=ranking,
         weight=weight,
-        nonce=nonce,
+        nonce=submission_nonce,
     )
 
     print("Ballot Hash Verification")
     print("=" * 60)
     print(f"Election ID:     {election_id}")
     print(f"Your ranking:    {ranking}")
     print(f"Weight:          {weight}")
-    print(f"Nonce:           {nonce}")
+    print(f"Nonce:           {submission_nonce}")
     print()
     print(f"Computed hash:   {computed_hash}")
     print(f"Expected hash:   {expected_ballot_hash}")

astra_app/core/templates/core/ballot_verify.html

@@ -40,7 +40,7 @@ <h3 class="card-title">Ballot receipt verification</h3>
 
         <form method="get" action="{% url 'ballot-verify' %}" class="mb-4" novalidate>
           <div class="form-group">
-            <label for="id_receipt">Receipt</label>
+            <label for="id_receipt">Ballot receipt code</label>
             <input
               type="text"
               class="form-control"
@@ -128,7 +128,7 @@ <h5>Ballot Information</h5>
                   <h5>Copy/paste constants for local verification</h5>
                   <p class="text-muted">
                     Copy/paste the block below into <strong><a href="{% static 'verify-ballot-hash.py' %}">verify-ballot-hash.py</a></strong>. It includes the election ID,
-                    candidate username-to-ID mapping, and where to find your credential public ID. You still need to enter your own vote choices
+                    candidate username-to-ID mapping, and where to find your voting credential. You still need to enter your own vote choices
                     in the script (vote choices are secret and are not shown on this page).
                   </p>
                   <pre class="bg-light p-3"><code>{{ verification_snippet }}</code></pre>

astra_app/core/templates/core/election_vote.html

@@ -93,7 +93,7 @@ <h3 class="card-title">Ballot</h3>
             <div class="alert d-none" id="election-vote-result" role="alert"></div>
 
             <div class="d-none" id="election-receipt-box">
-              <label class="text-muted" for="election-receipt">Receipt (ballot hash)</label>
+              <label class="text-muted" for="election-receipt">Ballot receipt code</label>
               <div class="input-group">
                 <input id="election-receipt" class="form-control" type="text" readonly />
                 <div class="input-group-append">
@@ -106,7 +106,7 @@ <h3 class="card-title">Ballot</h3>
               </div>
 
               <div class="mt-2">
-                <label class="text-muted" for="election-nonce">Ballot Nonce</label>
+                <label class="text-muted" for="election-nonce">Submission Nonce</label>
                 <input id="election-nonce" class="form-control" type="text" readonly />
                 <div class="form-text text-muted">Save this together with your receipt.</div>
               </div>

astra_app/core/views_elections/ballot_verify.py

@@ -98,7 +98,7 @@ def ballot_verify(request):
         lines: list[str] = [
             "# Copy/paste these values into verify-ballot-hash.py",
             f"election_id = {election.id}",
-            "# Locate your credential_public_id in the voting credential email you received.",
+            f"# Locate your voting credential in the first email you received, titled 'Your voting credential for {election.name}'.",
             "candidate_ids_by_username = {",
         ]
         for username in sorted(candidate_ids_by_username.keys(), key=str.lower):