docs(ST-1110.7): document three-layer demo-readonly policy and mirror plan
This commit is contained in:
parent
2647c14c09
commit
d832df3def
3 changed files with 109 additions and 1 deletions
|
|
@ -137,7 +137,7 @@ Volledige Zod-schema in `lib/env.ts`. `.env.example` is de canonieke lijst voor
|
|||
- **Toegangsmodel:** product-scoped resources gebruiken `productAccessFilter(userId)` tenzij het expliciet een eigenaarsactie is
|
||||
- **Bulk-ID's:** reorder- en beslissingsacties valideren dat alle meegegeven IDs binnen dezelfde parent-scope vallen voordat er geschreven wordt
|
||||
- **Foreign keys:** denormalized keys zoals `story.product_id` worden afgeleid uit de database-parent (`pbi.product_id`), nooit uit client-input
|
||||
- **Demo-check:** elke Server Action controleert `session.isDemo` vóór schrijven
|
||||
- **Demo-check (drie lagen — ST-1110):** write-acties zijn drielaags afgedekt: (1) middleware-guard in `proxy.ts` blokkeert non-GET op `/api/*` voor demo; (2) elke Server Action / Route Handler controleert `session.isDemo` vóór schrijven; (3) write-knoppen in UI zijn `disabled` met `<DemoTooltip show={isDemo}>`. Zie `docs/scrum4me-architecture.md#demo-user-policy` en `docs/plans/ST-1110-demo-readonly.md`
|
||||
- **Foutberichten:** Nederlands voor eindgebruikers — comments in code: Engels
|
||||
- **Dependencies:** elke geïmporteerde runtime package staat direct in `dependencies`, niet alleen transitief in `package-lock.json`
|
||||
- **Docs-sync:** elke gedrags-, dependency-, API- of deploymentwijziging werkt README, relevante docs en patterns bij in dezelfde change
|
||||
|
|
|
|||
62
docs/plans/ST-1110-demo-readonly.md
Normal file
62
docs/plans/ST-1110-demo-readonly.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
# Plan: ST-1110 — Demo gebruiker read-only
|
||||
|
||||
## Context
|
||||
|
||||
Demo-gebruikers (`is_demo=true` in DB) mogen de app niet muteren. Vóór ST-1110 was de beveiliging gemengd en inconsistent: sommige routes hadden een isDemo-check, sommige niet; UI-patronen waren inconsistent (deels verborgen, deels disabled+toast).
|
||||
|
||||
## Audit resultaten (ST-1110.1)
|
||||
|
||||
Gevonden beveiligingsgaten vóór ST-1110:
|
||||
- `/api/auth/pair/start` en `/api/auth/pair/claim`: geen isDemo-check
|
||||
- `/api/todos`, `/api/stories`, `/api/tasks` e.a.: hadden isDemo-check in actie, maar geen middleware-laag
|
||||
- UI: 24+ locaties gemengd patroon (`!isDemo && <Button>` of `disabled+toast`)
|
||||
|
||||
## Gekozen aanpak (ST-1110.2)
|
||||
|
||||
Drie-laagse bescherming:
|
||||
1. **Middleware-guard** in `proxy.ts` (defense in depth voor toekomstige routes)
|
||||
2. **Per-route guards** in Server Actions en Route Handlers
|
||||
3. **UI-laag**: uniform `disabled + DemoTooltip`
|
||||
|
||||
## M11-antwoorden
|
||||
|
||||
### ST-1110.4 — QR-pairing voor demo-gebruiker
|
||||
**Vraag:** Mag een demo-gebruiker een QR-pairing starten en claimen?
|
||||
**Opties:**
|
||||
- Blokken — voeg isDemo-check toe in pair/start en pair/claim, demo krijgt 403
|
||||
- Openhouden — geen wijziging; demo kan pair-flow starten maar approve faalt toch
|
||||
|
||||
**Antwoord (2026-04-29):** **Blokken**
|
||||
|
||||
**Implementatie:**
|
||||
- `pair/start`: `getIronSession(await cookies(), sessionOptions)` → 403 als `session.isDemo`
|
||||
- `pair/claim`: check `pairing.user?.is_demo` na DB-read → 403 + `clearPairCookie()`
|
||||
- proxy.ts DEMO_WRITE_ALLOWLIST bevat pair-paden NIET
|
||||
|
||||
### ST-1110.5 — Write-knoppen voor demo-gebruiker
|
||||
**Vraag:** Hoe write-knoppen tonen aan demo-gebruikers?
|
||||
**Opties:**
|
||||
- Verbergen — `{!isDemo && <Button />}`, minder visuele clutter
|
||||
- Disabled + tooltip "Niet beschikbaar in demo-modus" — bezoeker ziet wat de app kan
|
||||
|
||||
**Antwoord (2026-04-29):** **Disabled + tooltip**
|
||||
|
||||
**Implementatie:** Alle `!isDemo && <Button>` patronen omgezet naar `<DemoTooltip show={isDemo}><Button disabled={isDemo}>`.
|
||||
|
||||
## Bestanden gewijzigd
|
||||
|
||||
| Task | Commits | Bestanden |
|
||||
|---|---|---|
|
||||
| ST-1110.3 | `feat(ST-1110.3)` | `proxy.ts` |
|
||||
| ST-1110.3+4 | `feat(ST-1110.3+4)` | `proxy.ts`, `app/api/auth/pair/start/route.ts`, `app/api/auth/pair/claim/route.ts` |
|
||||
| ST-1110.5 | `feat(ST-1110.5)` | 12 component/pagina-bestanden |
|
||||
| ST-1110.5 tests | `test(ST-1110.5)` | `__tests__/api/pair-claim.test.ts`, `__tests__/api/pair-start.test.ts` |
|
||||
| ST-1110.6 | `test(ST-1110.6)` | `__tests__/proxy/demo-guard.test.ts` |
|
||||
| ST-1110.7 | `docs(ST-1110.7)` | `docs/scrum4me-architecture.md`, dit bestand |
|
||||
|
||||
## Aandachtspunten toekomstige stories
|
||||
|
||||
- Elke nieuwe write-route (Server Action of Route Handler) moet `session.isDemo` checken
|
||||
- De middleware-guard valt terug als defense in depth — niet als enige bescherming
|
||||
- Drag-and-drop handles blijven verborgen voor demo (`{!isDemo && <span {...listeners} />}`)
|
||||
- Nieuwe write-knoppen in UI: `<DemoTooltip show={isDemo}><Button disabled={isDemo}>`
|
||||
|
|
@ -1001,6 +1001,52 @@ Iron-session cookie of Bearer-token (demo). De auth-check loopt éénmalig bij d
|
|||
|
||||
---
|
||||
|
||||
## Demo-user policy (ST-1110)
|
||||
|
||||
Demo-gebruikers (`is_demo = true` in de database, `isDemo: true` in de iron-session) hebben volledig read-only toegang. Bescherming is drielaags:
|
||||
|
||||
### Laag 1 — Middleware-guard (proxy.ts)
|
||||
|
||||
`proxy.ts` blokkeert alle non-GET requests op `/api/*` voor demo-gebruikers voordat de route handler draait (defense in depth). Implementatie gebruikt `unsealData` direct (geen `getIronSession`) omdat `request.cookies` in middleware `RequestCookies` is, niet de volledige `CookieStore`.
|
||||
|
||||
```ts
|
||||
// Whitelist: paden die demo mag aanroepen ondanks non-GET
|
||||
const DEMO_WRITE_ALLOWLIST = [
|
||||
'/api/cron/', // machine-auth, irrelevant voor demo
|
||||
]
|
||||
// pair/start en pair/claim staan NIET in de allowlist — zie Laag 2
|
||||
```
|
||||
|
||||
### Laag 2 — Per-route guards (Server Actions & Route Handlers)
|
||||
|
||||
Elke schrijfactie controleert `session.isDemo` vóór DB-toegang:
|
||||
|
||||
```ts
|
||||
if (session.isDemo) return { error: 'Niet beschikbaar in demo-modus' }
|
||||
```
|
||||
|
||||
**QR-pairing (M10):**
|
||||
- `pair/start`: isDemo-check via `getIronSession(await cookies(), sessionOptions)` — blokkeert demo-desktops
|
||||
- `pair/claim`: check `pairing.user?.is_demo` na DB-read — blokkeert demo-users die op mobiel hebben goedgekeurd
|
||||
- `pair/approve` en `pair/cancel`: waren al geblokkeerd vóór ST-1110
|
||||
|
||||
**Realtime SSE en cron-routes:** niet relevant voor demo-bescherming (SSE is read-only, cron gebruikt Bearer-auth).
|
||||
|
||||
### Laag 3 — UI-laag (DemoTooltip)
|
||||
|
||||
Alle write-knoppen zijn `disabled` met een `DemoTooltip show={isDemo}` wrapper zodat demo-bezoekers de app-mogelijkheden kunnen zien. Consistente component: `components/shared/demo-tooltip.tsx`.
|
||||
|
||||
Patroon:
|
||||
```tsx
|
||||
<DemoTooltip show={isDemo}>
|
||||
<Button disabled={isDemo} onClick={() => !isDemo && handleAction()}>
|
||||
Actie
|
||||
</Button>
|
||||
</DemoTooltip>
|
||||
```
|
||||
|
||||
**Let op:** drag-and-drop handles (`⠿`) blijven verborgen voor demo (`{!isDemo && <span {...listeners} />}`) — dragging is geen UI-showcase maar zou nep-optimistische updates triggeren.
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variabele | Doel | Waar te vinden |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue