Calendar OAuth Connector — Phase 1D Frozen Spec (Google read-only)

Status: FROZEN spec (step 11a, Thinking tier) — 2026-07-05. Build = step 11b (Auto). No code, no OAuth client registration change, and no network in this document. Implementation is gated behind CALENDAR_OAUTH_GOOGLE_AUTHORIZED (hard-coded false) until seven-tier smokes pass and an operator flips the Tier 3 gate.

Parent spec: docs/CALENDAR-EVENTS-V0-SPEC.md (Phase 1D row). Scooling consumer contract: scooling/docs/CALENDAR-OAUTH-CONNECTOR-STEP-11-CONTRACT.md. Product plan: scooling/docs/CALENDAR-AND-SCHEDULE-PLAN.md.

Simple summary

A user connects their Google Calendar to Knowtation so their meetings show up on the Scooling schedule next to their notes. Knowtation only ever reads the calendar (never writes), stores the connection secret encrypted, and the user can disconnect at any time — which deletes the copied events. Agents get no access to these events until the user explicitly opts in, one calendar at a time.

Technical summary

Phase 1D adds a server-side, read-only Google Calendar OAuth 2.0 connector to Knowtation (canonical owner of tokens and events). It reuses the repo's hardened OAuth primitives — the pure PKCE core (lib/companion-oauth-pkce.mjs: S256-only, CSRF state, constant-time compares, fail-closed) and the AES-256-GCM + scrypt encryption-at-rest pattern (lib/memory-provider-encrypted.mjs) — rather than introducing new crypto. Scooling initiates consent and shows status only; it never holds a token and never calls Google directly.

This freeze resolves the deferred CalendarConnector endpoints (spec §"Deferred (1C+)") for the google provider only. ICS URL subscription (1C) is a separate freeze and is out of scope here.

Design decisions frozen in this spec

OAuth flow (server-side authorization code + PKCE)

Scooling wizard "Connect Google Calendar"
   │  CalendarAdapter.beginConnect('google', return_url)
   ▼
POST /api/v1/calendar/connectors  { provider:'google', display_name?, return_url }
   │  Knowtation: create PENDING connector; generate PKCE (S256) + state (CSPRNG, TTL 10m,
   │  bound to vault_id + connector_id + return_url); persist verifier+state server-side.
   ▼  { connector_id, authorization_url, expires_at }   (no secrets in URL beyond standard params)
Scooling opens authorization_url in the system browser
   ▼
Google consent screen (read-only scopes, offline)
   ▼  redirect to Knowtation callback (server-to-server code exchange)
GET /api/v1/calendar/connectors/callback?code=&state=
   │  validate state (constant-time, single-use, not expired, matches connector)
   │  exchange code + code_verifier + client_secret at token endpoint (server-side TLS)
   │  encrypt refresh_token → oauth_ref; DISCARD plaintext; access token kept in memory
   │  calendarList.list → create SourceCalendar rows (D9 defaults)
   │  initial events.list per calendar (D5/D6) → normalize (D8) → event store
   ▼  302 to allowlisted Scooling return_url  (NO token, NO code in the redirect)
Scooling shows connected account + sub-calendars (display on, agents off)

Redirect-URI and return_url are exact-match allowlisted (env CALENDAR_OAUTH_REDIRECT_URI, SCOOLING_RETURN_URL_ALLOWLIST). Open redirects are rejected fail-closed.

Data model additions

Extends CalendarConnector (V0 spec) for provider='google'. No client-visible field changes.

Encrypted blob (data/calendar_oauth/{connector_id}.enc, gitignored + museignored): { refresh_token, scope, token_type, obtained_at, account_sub }, AES-256-GCM, per-connector salt. client_id/client_secret come from env, are never written to the blob or store.

New module: lib/calendar/oauth-token-vault.mjs (encrypt/decrypt round-trip; injected secret; pure crypto, no logging) + lib/calendar/google-event-normalizer.mjs (pure Google event → CalendarEvent, no network; mirrors ics-normalizer.mjs).

Connector API (freezes V0 §"Deferred (1C+)" for google)

All routes under existing app.use('/api/v1/calendar', jwtAuth, apiLimiter, requireVaultAccess). All fail-closed when CALENDAR_OAUTH_GOOGLE_AUTHORIZED is false → 501 { code:'NOT_AUTHORIZED' }.

status enum: pending, connected, needs_reauth, revoked.

Revoke sequence (DELETE /connectors/:id)

1. Decrypt oauth_ref; call Google revocation endpoint https://oauth2.googleapis.com/revoke with the refresh token (best-effort; treat network failure as non-fatal to local purge).
2. Delete the encrypted blob file.
3. Delete all events whose source_calendar_id belongs to this connector (immediate).
4. Set revoked_at, status=revoked; keep a token-free tombstone record for audit.
5. Reconciliation sweep guarantees purge within the 24h SLA if step 3 partially failed.

invalid_grant on refresh (user revoked at Google) → set status=needs_reauth, last_sync_error=auth_expired, stop sync. Events are not auto-deleted on reauth-needed (user may reconnect); a hard DELETE is required to purge.

Security invariants (must hold — enforced, not documented-only)

• No secret/PII egress. Tokens, client_secret, authorization codes, code_verifier, state, and attendee/organizer data never appear in responses, redirects, logs, error messages, provenance, projections, or MCP resources. Errors carry fixed enum codes only.
• State/CSRF. state is CSPRNG, single-use, TTL 10m, bound to vault_id+connector_id+return_url, compared constant-time (reuse companion-oauth-pkce validators). Replay, tamper, and expiry → deny.
• PKCE S256 only. plain is rejected everywhere.
• Redirect allowlist. redirect_uri and return_url exact-match allowlisted; no open redirect.
• Read-only scopes only (D2). Any write scope is a separate future gate.
• Untrusted content. summary is untrusted prompt content; existing tier redaction (0–1 hide summary) and agent-context caps (enabled_for_agents=false, tier 0 default) apply unchanged.
• Least data. D8 drops attendees/location/description — they are never fetched into storage.
• Server-only provider calls. Scooling never calls Google; agents never call Google.
• Backoff. Respect Google 429/403 rateLimitExceeded with exponential backoff + Retry-After.
• Gate off = inert. With CALENDAR_OAUTH_GOOGLE_AUTHORIZED=false, no network, no token I/O; all connector routes return 501 NOT_AUTHORIZED.

Environment (secrets — never committed)

.gitignore + .museignore must exclude data/calendar_oauth/ and any *.enc token blobs.

Seven-tier test matrix (Knowtation — 11b Definition of Done)

All network is faked via an injected Google client (token endpoint + calendarList.list + events.list doubles). No live Google call in CI. Live smoke is operator-run behind the gate.

Test command: node --test test/calendar-oauth-connector-*.test.mjs.

Out of scope (separate freezes / gates)

• ICS URL subscription sync (1C) — separate freeze.
• Microsoft/Outlook OAuth — later provider.
• Write-back (create/update external events, invites) — separate high-risk gate.
• Tier 3–4 agent detail (location/description) — separate consent gate.
• Google app verification for public launch — separate operator/legal gate (D11).
• MCP/CLI connector parity — after Hub REST is proven.