familysync/.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-09-PLAN.md

phase, plan, type, wave, depends_on, gap_closure, autonomous, requirements, files_modified, must_haves

phase	plan	type	wave	depends_on	gap_closure	autonomous	requirements	files_modified	must_haves
03-event-write-back-pwa-install	09	tdd	1		true	true	CAL-04 CAL-05 CAL-06	apps/api/src/routes/events.ts apps/api/tests/routes/events.test.ts	truths artifacts key_links POST /api/events/create with the exact client CreateEventPayload shape ({title,start,end,allDay,recurrence}) returns 202, not 400 PATCH /api/events/:uid/edit with the same client shape returns 202, not 400 An authenticated OIDC request (devBypassActive=false) with a known iss+sub resolves to a real users.id and is allowed to write — it does NOT unconditionally 401 A request with no dev user and no OIDC session returns 401 path provides contains apps/api/src/routes/events.ts Canonical title/start/end zod contract + async OIDC iss/sub→users.id resolution on all 5 handlers upsertUser from to via pattern apps/api/src/routes/events.ts apps/api/src/auth/user.ts upsertUser(iss, sub, email) upsertUser(

Fix the route layer so the write path is reachable at all: align the server zod schema to the contract the PWA actually sends (CR-01), and implement the real OIDC iss/sub → users.id resolution that all five write/sync handlers stub out as a hard 401 today (CR-06). Without this plan every create/edit returns 400 in dev and 401 in production — the entire phase acceptance criterion is unreachable.

Purpose: make the events router accept real client requests under real Authelia auth. Output: an events router whose schema matches CreateEventPayload and whose OIDC path resolves authenticated members to a DB user via the existing upsertUser helper.

<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/03-event-write-back-pwa-install/03-REVIEW.md @.planning/phases/03-event-write-back-pwa-install/03-CONTEXT.md @apps/api/src/routes/events.ts @apps/api/src/auth/user.ts @apps/api/src/routes/me.ts @apps/pwa/src/api/client.ts

<artifacts_this_phase_produces> This gap plan introduces NO new exported symbols. It changes the in-module eventFieldsSchema field names and converts the private resolveUserId(c) helper into an async resolveUserId(c): Promise<number | null> that consults upsertUser. Downstream gap plans (03-10) read the new field names (title/start/end) out of calendarOutbox.payload. </artifacts_this_phase_produces>

Task 1: RED+GREEN — adopt the canonical title/start/end contract (CR-01) apps/api/src/routes/events.ts, apps/api/tests/routes/events.test.ts - apps/api/src/routes/events.ts (eventFieldsSchema at lines 67-77; create handler ~191; edit handler ~268) - apps/pwa/src/api/client.ts (CreateEventPayload at lines 119-128 — the authoritative client shape) - apps/api/tests/routes/events.test.ts (existing route tests — they currently pass because they send the SERVER field names; that is the wrong boundary the review flagged) - .planning/phases/03-event-write-back-pwa-install/03-REVIEW.md (CR-01) - RED: a new contract test imports the `CreateEventPayload` TYPE shape from the PWA client (or replicates it literally as `{title,start,end,allDay,recurrence}` with a comment citing client.ts:119-128) and POSTs it to /api/events/create — asserts 202, NOT 400. This fails today because zod requires summary/dtstart/dtend. - RED: a second test PATCHes the same shape to /api/events/:uid/edit — asserts 202, NOT 400. - GREEN: both pass after the schema is renamed. Canonical contract chosen: the SERVER adopts the CLIENT field names `title/start/end` (the PWA `CreateEventPayload`, `EventForm.handleSubmit`, and `createEvent`/`updateEvent` already send these — adopting them server-side requires zero PWA churn).

In events.ts rename `eventFieldsSchema` fields to exactly:
`title: z.string().min(1).max(255)`, `allDay: z.boolean()`,
`start: z.string().min(1).max(64)`, `end: z.string().min(1).max(64)`,
`location: z.string().max(2000).optional()`, `description: z.string().max(2000).optional()`,
`recurrence: z.enum(['none','daily','weekly','monthly','yearly']).optional()`,
`calendarUrl: z.string().url().max(1024).optional()`.
Keep `recurrence` `.optional()` server-side (the client always sends it, but the
contract drift the review noted resolves either way once names match).

The route still stores `payload: JSON.stringify(payload)` unchanged — the worker
(plan 03-10) now parses `title/start/end` from it. Do NOT introduce summary/dtstart/dtend
anywhere; do NOT add an internal rename map (the review's "map internally" alternative is
rejected to keep one canonical name set end-to-end).

Add the two contract tests described in <behavior>. Commit RED then GREEN
(`test(03-09): ...` then `feat(03-09): ...`).

cd apps/api && npx vitest run tests/routes/events.test.ts - behavior: POST /api/events/create with `{title,start,end,allDay,recurrence}` returns 202. - behavior: PATCH /api/events/:uid/edit with the same shape returns 202. - source: `grep -n 'summary\|dtstart\|dtend' apps/api/src/routes/events.ts` returns no matches in eventFieldsSchema. - test-command: `cd apps/api && npx vitest run tests/routes/events.test.ts` passes. The server schema accepts the exact payload the PWA sends; no create/edit is rejected at the validator boundary for field-name drift. Task 2: RED+GREEN — resolve OIDC iss/sub to a real users.id on all 5 handlers (CR-06) apps/api/src/routes/events.ts, apps/api/tests/routes/events.test.ts - apps/api/src/routes/events.ts (resolveUserId at lines 50-55; the five 401-stub blocks at ~194-200, ~270-273, ~374-377, ~439-442, ~492-495) - apps/api/src/auth/user.ts (upsertUser — the canonical iss/sub→users row helper already used by me.ts) - apps/api/src/routes/me.ts (the reference OIDC resolution pattern: getAuth → iss/sub/email → upsertUser) - .planning/phases/03-event-write-back-pwa-install/03-REVIEW.md (CR-06) - RED: a test that simulates the production OIDC path (no dev `c.get('user')`; `getAuth` mocked to return a valid `{iss, sub, email}`) POSTs /api/events/create and asserts the response is 202 AND that the row was attributed to the upserted user id (currentUserId != null). Fails today because the handler returns 401 even when auth is truthy. - RED: a test with no dev user and `getAuth` returning null asserts 401 (the genuinely-unauthenticated case still 401s). Convert `resolveUserId(c)` to an async helper `async function resolveUserId(c): Promise`: 1. If `c.get('user')` exists (dev bypass), return its `.id` (unchanged). 2. Else call `await getAuth(c)`. If falsy, return null (caller emits 401). 3. Else extract `iss = (auth.iss as string) ?? ''`, `sub = auth.sub ?? ''`, `email = typeof auth.email === 'string' ? auth.email : undefined`, then `const user = await upsertUser(iss, sub, email)` and return `user?.id ?? null`. Import `upsertUser` from `../auth/user.js`.

In each of the 5 handlers (create, edit, delete, sync-status, writable-calendars)
replace the `resolveUserId(...)` call + inline getAuth/401 stub block with:
`const currentUserId = await resolveUserId(c)` then `if (currentUserId === null) return c.json({ error: 'Unauthorized' }, 401)`.
Remove every `// For now return 401` stub and the now-redundant inner `getAuth` calls in the handlers.
Per D-10 identity is oidc_iss+oidc_sub; upsertUser keys on `uniq_oidc_identity`. Return 401 ONLY when no session exists (covered by upsertUser path).

Add the two tests in <behavior>. Commit RED then GREEN.

cd apps/api && npx vitest run tests/routes/events.test.ts - behavior: an OIDC request with known iss+sub resolves currentUserId != null and the write enqueues (202). - behavior: a request with neither dev user nor OIDC session returns 401. - source: `grep -c 'For now return 401' apps/api/src/routes/events.ts` returns 0. - source: `grep -c 'upsertUser' apps/api/src/routes/events.ts` returns >= 1. - test-command: `cd apps/api && npx vitest run tests/routes/events.test.ts` passes. Authenticated Authelia members resolve to a DB user id on every write/sync/writable-calendars handler in production; only genuinely unauthenticated requests 401. - `cd apps/api && npx vitest run tests/routes/events.test.ts` green. - `cd apps/api && npm run build` (or tsc) succeeds with the async resolveUserId signature.

<success_criteria> The events router accepts the real PWA payload and resolves real OIDC members. The write path is no longer dead-on-arrival at the route boundary (CR-01, CR-06 closed). </success_criteria>

Create `.planning/phases/03-event-write-back-pwa-install/03-09-SUMMARY.md` when done.