Legions of Necromancer - Mini App Requirements

1. Goal

Build a mini web app to save and resume board-game progress.

Users must be able to:

• Create a new game session.
• Update tracked stats (strength, skill, items, and more).
• Return later using a URL.
• Avoid mandatory login for first release.

2. Product Decision (Auth vs UUID)

Use capability-based guest access for V1.

• No required user login.
• Each session has:
  • session_id in URL (public identifier).
  • edit_token secret (write authorization).
• Store only a hash of edit_token in DB.
• Keep raw edit_token in HttpOnly cookie.

Reason:

• Better UX than forced auth.
• More secure than UUID-only edit links.
• Easy to add account auth later.

3. Core Functional Requirements

3.1 Create Session

• Endpoint creates new game session.
• Generate cryptographically random values:
  • session_id (UUID).
  • edit_token (high-entropy random string).
• Save edit_token_hash in DB.
• Set HttpOnly cookie with raw edit_token.
• Return URL with session_id only.

3.2 Load Session

• Read-only load by session_id.
• Return current game state:
  • Strength
  • Skill
  • Items
  • Optional notes / metadata
  • Version number

3.3 Save Progress

• Requires session_id + valid edit_token cookie.
• Validate payload with Zod server-side.
• Reject invalid ranges and oversized payloads.
• Use optimistic concurrency with version.
• On success:
  • Update state
  • Increment version
  • Update updated_at

3.4 Optional Share Mode

• Optional share_token can be added later for read-only sharing.
• Do not allow writes with share token.

4. Data Model Requirements (Supabase/Postgres)

4.1 Table: game_sessions

Required columns:

• id uuid primary key default gen_random_uuid()
• session_name text null
• state jsonb not null default '{}'::jsonb
• edit_token_hash text not null
• version integer not null default 1
• created_at timestamptz not null default now()
• updated_at timestamptz not null default now()
• last_played_at timestamptz not null default now()

Recommended checks:

• Ensure jsonb_typeof(state) = 'object'.
• Optional guard rails for expected shape in app validation.

Indexes:

• PK on id.
• Optional index on updated_at for cleanup jobs.

4.2 State Shape (application-level)

state should support:

• strength: number, min 0, max 100
• skill: number, min 0, max 100
• items: array of item objects
• gold: number, min 0
• notes: string, max length 2000

Example item shape:

• id: string
• name: string
• qty: integer >= 1

5. Security Requirements

5.1 Secrets and Keys

• Never expose service role key to browser.
• Write operations happen server-side only.
• Keep edit_token in HttpOnly, Secure, SameSite=Lax cookie.

5.2 Abuse Prevention

Implement all:

• IP-based rate limit on create-session endpoint.
• IP + session_id based rate limit on save endpoint.
• Request body size limits.
• Strict schema validation with Zod.
• Input sanitization for text fields.

Nice-to-have if abuse starts:

• CAPTCHA on create-session.
• WAF/bot protection at edge.

5.3 Authorization Rules

• Anyone with session_id can read only if policy allows.
• Only valid edit token holder can write.
• Invalid token returns 401/403 without leaking details.

6. API Requirements

6.1 POST /api/legions/session

Creates a session.

Response:

• sessionId
• version
• Optional initial state

Side effect:

• Sets edit token cookie.

6.2 GET /api/legions/session/:id

Loads session state.

Response:

• id
• state
• version
• updatedAt

6.3 PATCH /api/legions/session/:id

Saves progress.

Request body:

• state
• version (expected current version)

Responses:

• 200 success with new version
• 409 version conflict
• 401/403 auth failure
• 400 validation error

7. Validation Requirements (Zod)

• Shared schema for state validation.
• Coerce numeric input safely.
• Enforce min/max constraints.
• Reject unknown top-level fields unless explicitly allowed.

8. Frontend Requirements

• Keep form responsive and resilient.
• Debounce or batch save requests.
• Show clear save states:
  • Saving
  • Saved
  • Conflict
  • Error
• On conflict (409), offer reload and merge flow.

9. Reliability Requirements

• Use optimistic locking via version.
• Do not overwrite newer state with stale client state.
• Log server errors with request IDs.
• Add basic analytics for save failures and conflict rates.

10. Privacy and Retention

• Do not store unnecessary personal data in V1.
• Optional cleanup policy:
  • Delete inactive sessions after X days.
• Document retention rule in README.

11. Testing Requirements

Minimum automated tests:

• Zod schema validation success/failure cases.
• Session creation sets cookie and DB row.
• Save endpoint rejects invalid token.
• Save endpoint enforces version conflict.
• Rate limit behavior for write endpoints.

Manual test checklist:

• Create -> save -> reload works.
• Returning via URL restores progress.
• Invalid payload rejected.
• Parallel save tabs produce conflict handling.

12. Non-Goals (V1)

• No mandatory account system.
• No multiplayer sync.
• No full event-sourcing history (unless later needed).

13. V2 Upgrade Path

When needed, add optional login:

• Link guest sessions to user accounts.
• Allow account dashboard with all sessions.
• Keep guest flow for low-friction onboarding.

14. Definition of Done

V1 is done when:

• Session create/load/save endpoints work end-to-end.
• Edit token authorization is enforced.
• Rate limiting and payload validation are active.
• DB schema is migrated and tested.
• User can return via URL and continue safely.