User choices and UUID locks

VoterGuideOS can store voter-specific choices, such as selected candidates, ranked choices, retention votes, and ballot measure selections.

Unlike public ballot content, choice data is protected. A ballot ID is not enough to retrieve a voter's saved choices.

Why UUID Locks Exist

A ballot ID may be shared in links, browser history, logs, or support workflows. It should not grant access to a voter's saved selections.

To protect those selections, anonymous choice data is associated with a uuidLock. A UUID lock is a random value generated on the user's device and stored locally. When the API receives the same lock later, it can return or replace only the choices tied to that lock.

Generating a UUID Lock

When an anonymous voter begins interacting with a ballot, generate a UUID and store it on the device.

const uuidLock = crypto.randomUUID();

localStorage.setItem('uuidLock', uuidLock);

Reuse the same lock whenever anonymous choices are saved or retrieved for that voter.

Retrieving Choices

Include the uuidLock when requesting a ballot by ID.

const ballot = await client.service('ballots').get(ballotId, {
  query: {
    uuidLock
  }
});

If the lock matches, the ballot response includes the voter's saved raceChoices and measureChoices.

If the lock is missing or incorrect, ballot content is still returned, but anonymous choice data is omitted.

Recommended Storage

UUID locks should be stored locally on the user's device.

Common options include:

• localStorage
• sessionStorage
• IndexedDB
• Secure mobile app storage

UUID locks should not be shared between users. It should also not be generated or stored server-side.