# ADR-0006: Demo-user write protection enforced in three layers

## Status

accepted

## Context

Scrum4Me has a demo account that allows prospective users to explore the app without signing up. The demo user must never be able to create, update, or delete any data. A single guard at one layer is insufficient: a bug or a missing check in any one layer would expose a write path. See `docs/architecture/auth-and-sessions.md` and `docs/plans/ST-1110-demo-readonly.md` for implementation details.

## Decision

Write protection for the demo user is enforced at **three independent layers**:

1. **Network — `proxy.ts`:** The Next.js proxy middleware rejects all non-GET requests from demo sessions before they reach any route handler or server action.
2. **Server — every Server Action and Route Handler:** Each write endpoint checks `session.isDemo` and returns `403` immediately if true.
3. **UI — disabled buttons + `<DemoTooltip>`:** Write controls (create, edit, delete, reorder) are rendered as `disabled` with a tooltip explaining the demo restriction. No write request is ever sent.

## Consequences

### Positive

- Defense-in-depth: any single layer can fail independently without exposing a write path.
- Clear user feedback at the UI layer without relying on error responses.
- Straightforward to audit: search for `isDemo` to find all enforcement points.

### Negative

- Three enforcement sites for every new write operation — easy to miss one when adding a new feature.
- Mitigation: the `DemoTooltip` pattern is documented in `docs/patterns/` and enforced in code review.

## Updated 2026-05-12 — Exception for client-side UI preferences

PBI-80 relaxes the policy *for client-side UI preferences only*:

- **Allowed for demo:** product-switch and sprint-switch via URL navigation,
  filters/sort, layout state (split-panes, collapsed PBIs, selections) —
  routed through the in-memory `useUserSettingsStore`.
- **Why this is safe:** none of these touch the database. The demo user is a
  single shared row, but each visitor's browser holds its own Zustand store
  and URL state. A refresh resets to seed defaults; visitors never see each
  other's choices.
- **Unchanged — three-layer enforcement still applies to:** all data mutations
  (PBI/story/task/sprint create/update/delete/reorder), account fields
  (username, password, email), role assignment, QR-pairing, web-push, and any
  cron/webhook secrets.
- **Pattern for new demo-friendly features:** if it is UI state, route it
  through `useUserSettingsStore.setPref` (which already has a demo-fork at
  [stores/user-settings/store.ts:80](../../stores/user-settings/store.ts)) or
  pure URL navigation via `router.push`. Never call a server action for demo.
  See [docs/patterns/demo-client-state.md](../patterns/demo-client-state.md).