Lucas Berger
0b074cd568
Live spike against me@lucasberger.ca: one app password enumerated both account calendars (PROPFIND), and a REPORT fetched + cached 503 real events into MariaDB with correct D-13 timed/all-day handling (CAL-01). Per-member app-password model (D-09) validated; no cross-account ACL needed; no fallback required. Gate 2 (live Authelia/Pangolin login + SSE smoke test) remains pending operator action.
78 lines
4.3 KiB
Markdown
78 lines
4.3 KiB
Markdown
# CAL-08: Personal Calendar ACL Spike — Decision Record
|
|
|
|
**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: GO** (per-member app-password model — D-09)
|
|
|
|
---
|
|
|
|
## How to Run the Spike
|
|
|
|
```bash
|
|
cd apps/api
|
|
# build first (no tsx dependency): pnpm --filter @familysync/api build
|
|
FASTMAIL_EMAIL=<you@fastmail.com> \
|
|
FASTMAIL_APP_PASSWORD=<app-password-from-fastmail-settings> \
|
|
node dist/broker/spike.js
|
|
```
|
|
|
|
The script prints every calendar collection returned by Fastmail's CalDAV PROPFIND (URL,
|
|
displayName, ctag, syncToken). It never logs the password.
|
|
|
|
---
|
|
|
|
## Results
|
|
|
|
### Calendars Discovered
|
|
|
|
| displayName | URL | ctag returned? | syncToken returned? |
|
|
|-------------|-----|----------------|---------------------|
|
|
| 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 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**
|
|
|
|
**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.
|
|
|
|
**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 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.
|