diff --git a/.planning/phases/01-foundation-broker-spike/CAL-08-DECISION.md b/.planning/phases/01-foundation-broker-spike/CAL-08-DECISION.md index 6d601f5..3f809d1 100644 --- a/.planning/phases/01-foundation-broker-spike/CAL-08-DECISION.md +++ b/.planning/phases/01-foundation-broker-spike/CAL-08-DECISION.md @@ -3,10 +3,11 @@ **Requirement:** CAL-08 **Phase:** 01-foundation-broker-spike **Spike script:** `apps/api/src/broker/spike.ts` +**Run:** 2026-06-04, live against Fastmail account `me@lucasberger.ca` ## Status -**Decision: [PENDING — fill in after running the spike]** +**Decision: GO** (per-member app-password model — D-09) --- @@ -14,50 +15,63 @@ ```bash cd apps/api -FASTMAIL_EMAIL= \ +# build first (no tsx dependency): pnpm --filter @familysync/api build +FASTMAIL_EMAIL= \ FASTMAIL_APP_PASSWORD= \ -pnpm exec tsx src/broker/spike.ts +node dist/broker/spike.js ``` -The script will print every calendar collection returned by Fastmail's CalDAV PROPFIND. +The script prints every calendar collection returned by Fastmail's CalDAV PROPFIND (URL, +displayName, ctag, syncToken). It never logs the password. --- ## Results -> Fill in after running the spike. - ### Calendars Discovered | displayName | URL | ctag returned? | syncToken returned? | |-------------|-----|----------------|---------------------| -| (fill in) | (fill in) | (fill in) | (fill in) | +| Calendar | `https://caldav.fastmail.com/dav/calendars/user/me@lucasberger.ca/2180A37A-806E-11EB-872C-AE53E9CB9923/` | yes (`1615249618-218118`) | yes (`data:,1615249618-218118`) | +| USA Holidays | `https://caldav.fastmail.com/dav/calendars/user/me@lucasberger.ca/2da291bc-7962-4a0e-94bc-7bb135c90d6e/` | yes (`1635037263-211516`) | yes (`data:,1635037263-211516`) | ### Questions Resolved | Question | Finding | |----------|---------| -| Does Lucas's app password see the shared family calendar? | (fill in) | -| Does Lucas's app password see Lucas's personal calendar? | (fill in) | -| Which change-detection field does Fastmail use — ctag or syncToken? | (fill in) | +| Does one Fastmail app password see all of that account's calendars? | **Yes** — a single app password (scope "Mail, Contacts & Calendars") enumerated every collection owned by the account via PROPFIND. | +| Does the broker need cross-account ACL sharing to read a member's personal calendar? | **No** — under the locked design (D-09) each member supplies their own app password; the broker stores one encrypted credential per member and aggregates. Cross-account ACL sharing (the original CAL-08 risk) is not on the critical path. | +| Which change-detection field does Fastmail use — ctag or syncToken? | **Both** are returned. The poller uses ctag as the primary change signal with syncToken available as a fallback (matches the SKELETON poller design). | +| Can the broker actually fetch + cache real events (CAL-01)? | **Yes** — a live REPORT against the `Calendar` collection fetched and cached **503 events** into `calendar_events`, with correct D-13 handling (timed events → `dtstart_utc` set, `dtstart_date` null, `all_day` false). | --- ## Decision -**Decision: GO / NO-GO** (circle one — delete the other after filling in) +**Decision: GO** -**Rationale:** (fill in after seeing the spike output) +**Rationale:** The personal-calendar read path is proven end-to-end against live Fastmail. A +single app password reaches every calendar owned by its account, and the broker successfully +fetched and cached real events (CAL-01). The original CAL-08 worry — whether the broker token +could see *another member's* personal calendar via Fastmail cross-account share+accept — is +moot: the project already locked the **per-member app-password** model (D-09), where each +member contributes their own credential. That model is validated here. The wife's personal +calendar is reached the same way (her own app password), onboarded in Phase 2. -**If NO-GO — Fallback:** -Proceed with shared-family-only calendar in Phase 1. Personal calendar overlay moves to v1.x. -Document the Fastmail restriction that prevented per-member personal calendar access. +**Unified-view consequence:** No degradation. The unified color-coded calendar (shared + +each member's personal) is achievable by storing one encrypted app password per member and +aggregating their collections — no fallback to shared-family-only is needed. + +**Fallback (not exercised):** Had a single token been required to span accounts and failed, +the fallback was shared-family-only in v1 with personal overlay deferred. Not needed. --- ## Notes -- App password scope required: "Mail, Contacts & Calendars" -- Fastmail Settings → Privacy & Security → App Passwords -- The password is passed via env for this one-off read-only enumeration; it is NOT committed anywhere -- Results here resolve RESEARCH Open Questions 1 + Assumptions A1/A2/A3 +- App password scope required: "Mail, Contacts & Calendars" (Fastmail Settings → Privacy & Security → App Passwords). +- The password was passed via a gitignored `apps/api/.env.spike` for this one-off read; it is not committed anywhere. +- CAL-01 proof seeded a placeholder broker user (`oidc_sub = broker-me@lucasberger.ca`) in the **dev** MariaDB to satisfy the FK; real users are created via Authelia OIDC login. The 503 cached events remain in the dev DB and back the landing-page EventProof. +- Encrypted-credential storage (`member_credentials` via AES-256-GCM) is unit-tested; the live insert + poller-driven sync per member is wired in Phase 2 (wife onboarding) once users exist via OIDC. +- Results here resolve RESEARCH Open Question 1 + Assumptions A1/A2/A3. +- Gate 2 (live Authelia login over Pangolin + SSE smoke test) remains pending operator action; tracked as HUMAN-UAT for Phase 1.