nmor/the-claude-council/calendar-provider
Claude Code and agent skill by nmor/the-claude-council
- community
Checking that the SKILL.md file is still in the repository.
Patterns for integrating business calendar providers (Google Workspace, Microsoft 365, Zoho Workplace, business CalDAV). OAuth flow, push subscriptions, echo suppression, etag concurrency, and write-back via the outbox pattern.
Install
npx vskill@latest install nmor/the-claude-council/calendar-providerSKILL.md
The same SKILL.md was published earlier as nmor/the-claude-council/calendar-provider.
Calendar Provider Integration
Size budget: 17 KB —token-budget.mjs --check.
Companion skill to provider-research and the global official-docs-first rule. Activates when touching any calendar-provider integration code (lib/calendar/providers/*, calendar OAuth, sync, write-back, alarms).
Scope
Business providers only.
| Provider | Auth | Push? | Cron floor | |
|---|---|---|---|---|
| Google Workspace | OAuth — openid email profile calendar.events calendar.readonly | Yes — Push Notifications API, channel TTL 7 days, X-Goog-Channel-Token HMAC | n/a (push covers it) | |
| Microsoft 365 Business | OAuth — openid email profile offline_access Calendars.ReadWrite | Yes — Graph change notifications, TTL up to 4230 min, clientState HMAC | n/a | |
| Zoho Workplace | App-specific password — CalDAV caldav.zoho.com | No — Zoho has no push | 60s active tab, 5min otherwise | |
| Generic business CalDAV (Fastmail / Nextcloud / Posteo / mailbox.org) | App-specific password — caller-supplied URL | No — RFC 4791 has no push | 60s active, 5min otherwise |
Out of scope: Apple iCloud (consumer), personal Gmail / Outlook / Yahoo / Proton (consumer). Rejection lives in lib/emailDomainPolicy.ts at signup AND social-callback parity.
Required reading before any change
docs/provider-research/google-calendar.md— scopes, push channel
TTL, Workspace admin-policy interactions.
docs/provider-research/microsoft-graph.md—Calendars.ReadWrite
vs Calendars.ReadWrite.Shared, tid claim for tenant rejection, change-notification renewal.
docs/provider-research/zoho-workplace.md— Application-Specific
Password format, Workplace server URL distinct from personal Zoho.
docs/provider-research/fastmail-nextcloud-posteo.md— per-provider
server URL formats.
If any of these doesn't exist or hasn't been touched within 6 months, refresh it first (see provider-research skill).
Core invariants
1. Email-match server-side
A user signed in as alice@acme.com can ONLY connect a calendar whose verified email matches alice@acme.com. Enforced in calendarOAuth.ts after the token exchange, before persisting the connection. Mismatch → 403 email_mismatch + audit row.
For CalDAV, verify the current-user-principal returned by PROPFIND matches the username the user entered.
2. Cell-bound + plan-gated
Every read/write route runs through authenticate() (cell check) + checkFeature(orgId, "calendarImport") (PRO+). Write routes additionally check the per-connection writable flag and the per-feature auto_write_prefs toggle.
3. Token refresh persistence
When the provider returns a refreshed access token, the calling lib MUST persist it back to the connection row via the shared persistRefreshedTokens helper. NOT persisting means every sync re-refreshes from the (potentially long-since-rotated) refresh token — wastes API calls and trips reuse-detection.
Code shape:
4. Echo suppression on push
When we write to a provider, we stamp the event with app_origin_id extended property. The provider push channel then sends the event back to us as a "new event". The sync worker:
- Looks up the row via the
origin_indexGSI by
app_origin_id.
- If status =
pending_external_write: reconcile (update etag +
external_event_id, flip to synced).
- If status =
synced: no-op (recognise our own echo). - If status =
syncedAND local copy is stale: provider wins on
title/time, we keep alarm bindings.
Without this the sync creates a duplicate for every event we wrote.
5. Etag-guarded writes
On update, supply the cached external_etag. On 412 Precondition Failed:
- Re-fetch the latest provider state.
- Three-way merge (provider wins on title/time, we keep alarm
bindings).
- Retry up to 3×.
- On persistent failure → status
write_conflict+ audit row + UI
banner.
6. Outbox-published writes
Manual writes (user clicks "+ Add event" or any "mirror to calendar" path) go through lib/outbox.ts so retries and DLQ routing are handled centrally. The HTTP response is 202 with the local row already visible to the client. The outbox worker dispatches via lib/calendar/writeBack.ts.
Idempotency key: cal:write:<app_origin_id>:v<version>.
7. PII envelope at rest
Event title, description, attendees are encrypted via the piiEncryption.ts envelope. Free/busy buckets never decrypt — only the per-event detail dialog does.
8. Cron-fallback active-window logic
CalDAV (Zoho + generic) connections poll on a 60s cron when the user has had a WS connection open in the last 5 min (active-user fast path), 5min otherwise. last_active_at is stamped by the useCalendarSocket composable. Without this signal the default floor is 15 min.
9. Write-back consent toggles
Auto-write per source-type (task, todo, standup_run, okr_checkin, roadmap_milestone, poll_book, invite, ai_event) is opt-in per user in users.calendar_auto_write_prefs. Default OFF for every auto path. Manual writes (the /calendar view's "+ Add event" button, poll closing, AI confirmation dialog) are always allowed.
10. Health-sweep + reconnect banner
calendarHealthSweep cron runs hourly. After 3 consecutive 401/403 returns from a provider, the connection is flipped to status=token_expired (refreshable) or status=revoked (not), an audit row is written, and the frontend shows a sticky "Reconnect <provider>" banner.
Test contract
For every provider-touching change:
- OAuth happy-path test — calls the provider mock, verifies
email-match guard, persists encrypted tokens.
- OAuth email-mismatch test — verifies 403
email_mismatch+
audit row.
- Sync echo-suppression test — writes a row, simulates provider
push, asserts no duplicate.
- Etag conflict test — provider returns 412, asserts three-way
merge + status transition.
- Token-refresh-persistence test — fakes a refresh, asserts the
connection row's access_token_encrypted field changed.
- Health-sweep test — 3 consecutive 401s, asserts status
transitions + banner-emit hook.
Cross-references
~/.claude/rules/common/official-docs-first.md— primary-source
citations required.
provider-researchskill — workflow for the citations.~/.claude/rules-library/common/no-discards.md— refresh-token rotation
must be bound + persisted, never dropped.
- The consuming project's
docs/<calendar-feature>.md— feature
page describing user-visible behaviour.
- The consuming project's
docs/runbook.md— recovery procedures
for reconnect / token-expiry / write-conflict states.
Purpose
Principal-level multi-provider calendar integration: OAuth scope negotiation (read vs write vs free-busy), incremental sync via syncToken (Google) / delta queries (Microsoft Graph) / CTag + ETag (CalDAV), push notification channels with TTL rotation (Google watch, Graph change-notifications, CalDAV WebDAV-Sync), write conflict resolution (ETag If-Match), recurring-event expansion (RFC 5545 RRULE), timezone correctness, business-tier vs personal-tier rejection at sign-up, refresh-token storage with rotation detection, and the iMIP / iTIP message contracts for invite + reply flows.
Negative scope (NOT what this skill covers):
- Calendar UI components — out
- Local calendar (.ics file) parsing in isolation — see RFC 5545
directly
- iCloud consumer-tier integration — explicitly out per
business-tier scope policy
- Custom scheduling logic (free-busy availability matching) — see
domain-specific scheduling skills
When NOT to use
- Single-provider integrations where multi-vendor abstraction is
premature (Google-only) — wire directly to the SDK
- Read-only consumption of an exported
.icsURL with no live
sync — parse the file; no provider integration needed
- Synchronous one-shot lookups (e.g., "what's my next meeting")
where push channels are over-engineered
Standards Cited
- RFC 4791 (CalDAV) — calendar access via WebDAV
- RFC 6638 (CalDAV Scheduling) — invite + reply protocol
- RFC 5545 (iCalendar) — VCALENDAR / VEVENT / RRULE format
- RFC 5546 (iTIP) — calendar transport
- RFC 6047 (iMIP) — iCalendar over MIME (email-borne invites)
- RFC 6749 (OAuth 2.0) — auth framework
- RFC 7636 (PKCE) — public-client flow
- Google Calendar API v3 docs (developers.google.com/calendar)
- Microsoft Graph API v1.0 (learn.microsoft.com/graph)
- W3C Push API (web push channel deliveries on the client side)
- OWASP ASVS 4.0.3 §3.5 (Token-based Session Management) —
refresh-token rotation + reuse detection
- OWASP ASVS 4.0.3 §4 (Access Control) — per-tenant scope
enforcement
Anti-Patterns
| Pattern | Why bad | Correct alternative | |
|---|---|---|---|
| Full sync on every poll | API quota burn; slow | syncToken / delta-query incremental sync | |
| Push channel without TTL renewal cron | Watch expires (Google: 7 days), updates silently stop | Scheduled re-subscribe before expiration | |
| Storing refresh token unencrypted | Vault breach = calendar access for every user | Encrypt at field level + rotate on reuse | |
| Single-write without ETag | Lost update on concurrent edit | If-Match: <etag> + 412 retry on conflict | |
| Timezone derived from server clock | Wrong-day bug across DST + cross-region users | Always include TZID + canonical IANA zone | |
| Treating personal Gmail as Workspace | Wrong scope set; tenant policy mismatch | Reject at signup via tid claim / email-domain blocklist | |
Ignoring cancelled / tentative status | Stale UI shows past invites | Parse STATUS: field on every event | |
| RRULE expansion in DB query | Cartesian explosion | Expand on demand at read-time, capped horizon | |
| Polling for write confirmation | Race + duplicate writes | Push notification + idempotency key | |
| Single-provider abstraction leaking to UI | Switching cost on second provider is total rewrite | Domain-shape boundary + adapter per provider |
Verification Checklist
- [ ] OAuth scope is minimum-necessary (read vs write vs free-busy)
- [ ]
docs/provider-research/<provider>.mdexists + cites primary
sources per official-docs-first.md
- [ ] Refresh-token rotation + reuse-detection wired
- [ ] Personal-tier vs business-tier rejected at sign-up
(documented in plan + handler)
- [ ] Incremental sync uses
syncToken/ delta / CTag (no
poll-and-diff)
- [ ] Push channel TTL renewal cron scheduled
- [ ] ETag
If-Matchon every write - [ ] Timezone stored as IANA zone +
TZIDround-tripped - [ ] RRULE expansion capped to a horizon (e.g., 18 months out)
- [ ] iMIP / iTIP message handling tested (accept / decline /
counter)
- [ ] Webhook signature verification on every change notification
- [ ] Audit log of every write per
audit-logging.md - [ ] Failure modes documented in
docs/runbook.md
Cross-References
~/.claude/skills/provider-research/SKILL.md— primary-source
citation discipline
~/.claude/skills/web-push-notifications/SKILL.md— sister
notification surface
~/.claude/skills/api-design/SKILL.md— calendar API consumer
patterns
~/.claude/rules/common/official-docs-first.md— provider docs
research mandate
~/.claude/rules-library/common/secrets-management.md— refresh-token
storage
~/.claude/rules-library/common/audit-logging.md— write audit~/.claude/agents/security-reviewer.md— Council Division 4~/.claude/agents/architect.md— Council Division 1
Why this skill exists
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/calendar-provider/SKILL.md
Popularity
- 7-day trend score
- 5
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/nmor/the-claude-council/calendar-provider)