nmor/the-claude-council/calendar-provider

Claude Code and agent skill by nmor/the-claude-council

Trust tier 3
  • community
Source check pending

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-provider

SKILL.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.

ProviderAuthPush?Cron floor
Google WorkspaceOAuth — openid email profile calendar.events calendar.readonlyYes — Push Notifications API, channel TTL 7 days, X-Goog-Channel-Token HMACn/a (push covers it)
Microsoft 365 BusinessOAuth — openid email profile offline_access Calendars.ReadWriteYes — Graph change notifications, TTL up to 4230 min, clientState HMACn/a
Zoho WorkplaceApp-specific password — CalDAV caldav.zoho.comNo — Zoho has no push60s active tab, 5min otherwise
Generic business CalDAV (Fastmail / Nextcloud / Posteo / mailbox.org)App-specific password — caller-supplied URLNo — RFC 4791 has no push60s 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:

ts
const client = await buildGoogleCalendarClient(connection, {
onTokenRefresh: (newTokens) =>
persistRefreshedTokens(connection.connection_id, newTokens),
});
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:

  1. Looks up the row via the origin_index GSI by

app_origin_id.

  1. If status = pending_external_write: reconcile (update etag +

external_event_id, flip to synced).

  1. If status = synced: no-op (recognise our own echo).
  2. If status = synced AND 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:

  1. Re-fetch the latest provider state.
  2. Three-way merge (provider wins on title/time, we keep alarm

bindings).

  1. Retry up to 3×.
  2. 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:

  1. OAuth happy-path test — calls the provider mock, verifies

email-match guard, persists encrypted tokens.

  1. OAuth email-mismatch test — verifies 403 email_mismatch +

audit row.

  1. Sync echo-suppression test — writes a row, simulates provider

push, asserts no duplicate.

  1. Etag conflict test — provider returns 412, asserts three-way

merge + status transition.

  1. Token-refresh-persistence test — fakes a refresh, asserts the

connection row's access_token_encrypted field changed.

  1. 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-research skill — 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 .ics URL 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

PatternWhy badCorrect alternative
Full sync on every pollAPI quota burn; slowsyncToken / delta-query incremental sync
Push channel without TTL renewal cronWatch expires (Google: 7 days), updates silently stopScheduled re-subscribe before expiration
Storing refresh token unencryptedVault breach = calendar access for every userEncrypt at field level + rotate on reuse
Single-write without ETagLost update on concurrent editIf-Match: <etag> + 412 retry on conflict
Timezone derived from server clockWrong-day bug across DST + cross-region usersAlways include TZID + canonical IANA zone
Treating personal Gmail as WorkspaceWrong scope set; tenant policy mismatchReject at signup via tid claim / email-domain blocklist
Ignoring cancelled / tentative statusStale UI shows past invitesParse STATUS: field on every event
RRULE expansion in DB queryCartesian explosionExpand on demand at read-time, capped horizon
Polling for write confirmationRace + duplicate writesPush notification + idempotency key
Single-provider abstraction leaking to UISwitching cost on second provider is total rewriteDomain-shape boundary + adapter per provider

Verification Checklist

  • [ ] OAuth scope is minimum-necessary (read vs write vs free-busy)
  • [ ] docs/provider-research/<provider>.md exists + 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-Match on every write
  • [ ] Timezone stored as IANA zone + TZID round-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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/nmor/the-claude-council/calendar-provider/badge)](https://verified-skill.com/skills/nmor/the-claude-council/calendar-provider)

Something wrong with this skill or its page? Tell us.