Add secure guest ballot creation API

[ejones23]

Summary

• add a typed POST /api/v2/ballots.php contract for name-and-candidates guest creation
• generate the shortcode, 256-bit management token, and internal owner marker on the server
• store only the management-token SHA-256 digest and return the raw credential once with Cache-Control: no-store
• force basic single-seat defaults and ignore caller-supplied identity or advanced settings
• mask the internal owner marker on public reads and close unauthenticated legacy entry/graph mutation bypasses
• add the production migration, schema-parity fixture, API documentation, and PHP contract tests

Verification

• npm test: 191 Vitest tests; 231 PHPUnit tests / 587 assertions
• PHP syntax checks for every changed endpoint
• live MySQL: creation, digest match, public read, and blocked legacy mutation verified with a disposable ballot and cleanup
• git diff --check

Deployment note

Apply src/api/migrations/2026-09-06-ballot-management-tokens.sql before deploying this endpoint and its legacy mutation guards.

Stack

This PR stacks on #80, which records the corresponding maintainer guidance in the RFC.

[DavidMoritz]

This is seriously impressive backend work. The security model is rock-solid — 256-bit server-generated token, SHA-256 digest storage, unpredictable native owner markers masked from public reads, and Cache-Control: no-store on the response. The input validation is thorough (UTF-8 checks, control characters, dedup), and the transaction handling pragmatically accounts for MyISAM's limitations. Six comprehensive PHPUnit tests covering the happy path, validation edge cases, and legacy mutation blocking. Top-notch engineering. Thank you for all this effort!