docs: WS-7 PR-2 follow-up — RFC §3.6 + §3.14 + BACKLOG OBS entries
RFC §3.6 — context tagging tabel volledig vervangen na de PR-2 follow-up architecturale fixes. Belangrijkste wijzigingen: - Tag-binding gesplitst in route-scope (BindSentryRouteContext middleware) en auth-scope (AuthScopeContextListener op Authenticated event). - Nieuwe actor_scope tag (organisation/platform/user/anonymous). - Multi-tenant invariant verfijnd: organisation_id is altijd correct gerelateerd aan actor_scope in plaats van "altijd aanwezig". Platform- routes zonder org-context worden niet meer gefabriceerd; default authenticated user-scope omitt organisation_id (Crewli's User<->Organisation is many-to-many, geen reliable single-org hint). - impersonation.* tags expliciet gedocumenteerd als afkomstig uit HandleImpersonation middleware (post-swap), niet uit auth-listener. - ActorType waarden bijgewerkt na verwijdering van VOLUNTEER case. RFC §3.14 — status-note toegevoegd dat D-06 indexes al via Spatie's nullableMorphs default-migratie zijn aangemaakt, met regression-guard verwijzing. §6 acceptance criterium 12 markeert D-06 als al voldaan. BACKLOG.md krijgt vier nieuwe OBS-entries: - OBS-1: VOLUNTEER actor_type promotion wanneer rol komt - OBS-4: PHPUnit metadata deprecation cleanup pre-PHPUnit-12 - OBS-6: sentry-laravel install gap awareness + bootstrap test - OBS-7: custom render handlers report() invariant + coverage Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -61,24 +61,41 @@ Format `<app>@<short-sha>` (`crewli-api@f41951a`, `crewli-app@f41951a`). Bron: `
|
||||
|
||||
### 3.6 Context tagging
|
||||
|
||||
| Tag | API | apps/app |
|
||||
|---|---|---|
|
||||
| `release` | altijd | altijd |
|
||||
| `environment` | altijd | altijd |
|
||||
| `app` | `api` | `app` |
|
||||
| `route_name` | `Route::currentRouteName()` | `route.name` |
|
||||
| `http.method` | altijd | n.v.t. |
|
||||
| `organisation_id` (ULID) | wanneer auth+scope gebound | uit auth store |
|
||||
| `event_id` (ULID) | wanneer event-scoped | wanneer applicabel |
|
||||
| `user_id` (ULID) | `auth()?->id()` | uit auth store, alleen session-mode |
|
||||
| `actor_type` | `organizer_admin` / `super_admin` / `portal_token` / `volunteer` / etc. | mirror |
|
||||
| `impersonation.active` | bool | n.v.t. |
|
||||
| `impersonation.impersonator_user_id` | wanneer actief | n.v.t. |
|
||||
| `queue.attempt` | binnen job-context | n.v.t. |
|
||||
Tag-binding gebeurt op twee plekken: route-scope tags via `BindSentryRouteContext` middleware (op de api-group), auth-scope tags via `AuthScopeContextListener` op `Illuminate\Auth\Events\Authenticated`. De split volgt de data-bron: route-context is alleen tijdens HTTP-handling beschikbaar, auth-context wordt door elke authenticator (Sanctum, portal-token) ge-emit via het Authenticated event.
|
||||
|
||||
| Tag | API | apps/app | Bron / locatie |
|
||||
|---|---|---|---|
|
||||
| `release` | altijd | altijd | env, sentry-laravel built-in |
|
||||
| `environment` | altijd | altijd | env, sentry-laravel built-in |
|
||||
| `app` | `api` | `app` | route-middleware |
|
||||
| `route_name` | altijd | altijd | route-middleware |
|
||||
| `http.method` | altijd | n.v.t. | route-middleware |
|
||||
| `actor_scope` | `organisation`/`platform`/`user`/`anonymous` | mirror | auth-listener (zie hieronder) |
|
||||
| `organisation_id` (ULID) | aanwezig wanneer `actor_scope = organisation` | uit auth store | auth-listener |
|
||||
| `event_id` (ULID) | wanneer event-scoped | wanneer applicabel | auth-listener (via {event} route-param) |
|
||||
| `user_id` (ULID) | wanneer authenticated | uit auth store, alleen session-mode | auth-listener |
|
||||
| `actor_type` | `organizer_admin` / `super_admin` / `portal_token` / `org_member` / `unauthenticated` | mirror | auth-listener |
|
||||
| `impersonation.active` | bool | n.v.t. | HandleImpersonation middleware (post-swap) |
|
||||
| `impersonation.impersonator_user_id` | wanneer actief | n.v.t. | HandleImpersonation middleware |
|
||||
| `impersonation.session_id` | wanneer actief | n.v.t. | HandleImpersonation middleware |
|
||||
| `queue.attempt` | binnen job-context | n.v.t. | TagJobAttemptOnSentry listener |
|
||||
|
||||
**Nooit als tag:** email, telefoon, naam, IP-adres, raw form_value content, raw cookie content.
|
||||
|
||||
Multi-tenant invariant: élke captured event uit een geauthenticeerde controller MOET `organisation_id` hebben. Een unit-test verifieert dit — als `organisation_id` ontbreekt op een geauthenticeerd path, faalt de test.
|
||||
**Multi-tenant invariant (verfijnd na PR-2 live smoke test):**
|
||||
|
||||
`actor_scope` is altijd aanwezig op authenticated events. Wanneer `actor_scope = organisation`, MOET `organisation_id` aanwezig en valide ULID zijn. Wanneer `actor_scope = platform`, IS `organisation_id` afwezig — dat is correct gedrag voor super_admin platform-routes (geforceerde org-attribution zou misleidend zijn). Wanneer `actor_scope = user` (default authenticated zonder org-route-context), is `organisation_id` ook afwezig: Crewli's User↔Organisation is many-to-many, een single-org "current org" bestaat niet op user-niveau, en attribution aan een willekeurige org zou misleiden. Een unit-test in `AuthScopeContextListenerTest::test_organisation_id_present_when_actor_scope_is_organisation` verifieert deze invariant.
|
||||
|
||||
**`actor_scope`-waarden:**
|
||||
|
||||
| Waarde | Wanneer | Filtering use-case in GlitchTip |
|
||||
|---|---|---|
|
||||
| `organisation` | route met {organisation} of {event} param, of portal-token request | "Issues voor organisatie X" |
|
||||
| `platform` | super_admin op `admin.*` named routes | "Platform-bugs (niet org-specifiek)" |
|
||||
| `user` | authenticated user op routes zonder org-scope (`/me/*`, `/portal/my-shifts`, `/uploads/*` etc.) | "Issues op user-routes; geen org-attribution" |
|
||||
| `anonymous` | unauthenticated requests | "Public-route issues" |
|
||||
|
||||
**Wijziging t.o.v. originele RFC:** de oorspronkelijke formulering "élke captured event uit een geauthenticeerde controller MOET `organisation_id` hebben" is verfijnd na bevinding dat super_admin platform-routes geen zinvolle org-context hebben en Crewli's many-to-many user-org model geen reliable single-org hint biedt. Het invariant is nu sterker: niet "altijd aanwezig" maar "altijd correct gerelateerd aan `actor_scope`."
|
||||
|
||||
### 3.7 PII scrubbing
|
||||
|
||||
@@ -143,6 +160,8 @@ Log::withContext([
|
||||
|
||||
`(subject_type, subject_id)` en `(causer_type, causer_id)` composite indexes op `activity_log`. Infrastructure-housekeeping; geen functionele wijziging.
|
||||
|
||||
**Status (mei 2026, na PR-2):** Bij implementatie bleek dat de Spatie activitylog default-migratie via `nullableMorphs('subject')` en `nullableMorphs('causer')` deze composite indexes al aanmaakt (`subject` op `(subject_type, subject_id)`, `causer` op `(causer_type, causer_id)`). Geen aparte migratie nodig — geverifieerd via `information_schema.STATISTICS`. Acceptance criterium 12 daarmee al voldaan vóór WS-7 begon. Regression-guard: `tests/Feature/Database/ActivityLogIndexesTest.php` faalt wanneer een toekomstige refactor deze indexes verwijdert.
|
||||
|
||||
---
|
||||
|
||||
## 4. Privacy / GDPR
|
||||
@@ -194,7 +213,7 @@ WS-7 is compleet wanneer:
|
||||
9. Email-alerting geconfigureerd; getest met sample issue.
|
||||
10. Retention-policy (90 dagen) toegepast.
|
||||
11. Daily postgres-backup-script in place.
|
||||
12. Activity_log indexes (addendum D-06) gemigreerd.
|
||||
12. ~~Activity_log indexes (addendum D-06) gemigreerd.~~ ✓ — al voldaan door Spatie's `nullableMorphs` default in de originele activitylog migratie; zie §3.14 status-note. Regression-guard: `tests/Feature/Database/ActivityLogIndexesTest.php`.
|
||||
13. Structured logging conventie geïmplementeerd; `X-Request-Id` round-trip getest.
|
||||
14. SECURITY_AUDIT.md bijgewerkt.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user