bernardo/nocal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(sync): add Microsoft Graph read adapter

Browse Source 
Add strict /me identity, atomic paged calendar discovery, and resumable primary-calendar v1 delta synchronization through the durable provider cache. Keep opaque continuations on trusted Graph URLs and retain credentials only per operation.

Document that stable Graph v1 delta covers only the primary calendar; secondary calendars still require a v1 reconciliation or beta dependency decision.

Verified: 18/18 normal, 18/18 -Werror, and 18/18 ASan/UBSan tests.
This commit is contained in:
Bernardo Magri
2026-07-18 12:34:21 +01:00
parent 3560a7d23d
commit 0582444c61
9 changed files with 1957 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/PRODUCT.md
View File

@@ -169,11 +169,35 @@ parsing, and storage failures are reported distinctly, with no plaintext
fallback and no partially connected account. Connection state is published
only after the complete secret store succeeds.
This phase still does not make Office 365 usable. It contains no Microsoft Graph
call, account UI, or usable account setup. After verification, the next product
slice calls `/me`, discovers calendars, and performs read-only Graph delta
synchronization using delegated `Calendars.Read`. Remote writes remain gated on
the durability and conflict paths being exercised end to end.
The Microsoft Graph read phase keeps Nocal a public desktop multitenant
application for organizational and personal
Microsoft accounts. It requests delegated `User.Read` for `/me` and delegated
`Calendars.Read` for calendars and events. Neither normally requires
administrator consent, although tenant policy may require approval or block
user consent. Access tokens are passed only to the operation that needs them;
Secret Service retains the persistent token set.
Calendar discovery reads every page and publishes an atomic replacement only
after the full listing succeeds. Stable provider/account identity gives each
calendar a deterministic local ID. Event reads request immutable Graph IDs and
use strict bounded parsing with credential-safe failures. Requests and opaque
next/delta links are restricted to HTTPS `graph.microsoft.com` URLs.
Event windows are half-open UTC intervals. Each event page, its deletions, and
its continuation cursor cross the cache boundary in one transaction. A partial
round can resume from its durable cursor, and deletion tombstones remain
explicit instead of silently dropping remote state.
The stable Graph v1.0 `calendarView` delta API is documented only for the
primary calendar. This slice discovers all calendars but delta-syncs only the
primary; it uses neither beta nor undocumented per-calendar routes. Secondary
calendar support requires a deliberate choice between v1 full-window
reconciliation with defined deletion semantics and beta-specific delta. Nocal
does not yet claim Outlook-equivalent coverage.
There is still no account UI/CLI orchestration or live Microsoft credential
integration, and remote writes remain out of scope. Account setup/orchestration
and the secondary-calendar reconciliation decision are the next product phase.
## Local file interchange