Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Spec: specs/pf/specs/PF-101-google-workspace-integration.md Plan: specs/pf/plans/PF-101-google-workspace-integration-PLAN.md Tasks: specs/pf/tasks/PF-101-TASKS.md Integration contract: docs/architecture/integrations/PF-101-google-workspace-integration-INTEGRATION.md Status: Alpha — WS1/WS2/WS5 complete; WS6 partial; WS7 in progress.

​
What this integration does

PF-101 makes Google Workspace a first-class platform connector alongside Microsoft Entra. It owns:
  • Directory lifecycle — provision / suspend / restore Workspace users from HR-01 employee events.
  • Gmail — outbound mail via Workspace Domain-Wide Delegation, replacing the legacy GMAIL_SERVICE_ACCOUNT_JSON env-only path.
  • Calendar + Meet — event creation and Meet conferencing for CE scheduling.
  • Licensing — assign / revoke Google licenses (e.g., Google-Apps-For-Business) per user.
  • Reports — ingest admin, login, and token audit activities into pf_audit_log (actor email SHA-256 hashed; no PHI).
  • Drive (deferred) — metadata-only mapping in MVP; explicit PF-11 export/import for content.
  • Chat (deferred) — PHI is always blocked; only PF-10 approved templates allowed.

​
Multi-tenant model

  • One row in pf_google_workspace_connections per (organization_id, primary_domain).
  • All four PF-101 tables ENABLE and FORCE row level security and use the canonical pf_has_org_access / pf_is_org_admin SECURITY DEFINER helpers.
  • Service account JSON, OAuth client secrets, and refresh tokens never live in tables, env vars, or logs — they resolve through PF-76 Credential Vault by stable credential_vault_ref.

​
Capability flags & PHI gating (fail-closed)

Every Workspace operation runs through assertCapabilityAllowed(connection, capability) in supabase/functions/_shared/google-workspace-client.ts. The check denies by default and requires:
  1. The capability column is true on the connection (e.g., capability_gmail_enabled).
  2. For PHI-capable capabilities (Gmail, Calendar, Drive, Chat), baa_attested_at IS NOT NULL.
  3. Sender domain (Gmail) matches the connection’s primary_domain allowlist.
Failed checks short-circuit before any Google API call and write a row to pf_google_workspace_sync_runs with status = 'failed' and a sanitized reason_code — never the error body.

​
Edge functions

FunctionPurposeTrigger
google-workspace-test-connectionPer-capability health check (Directory, Gmail, Calendar, …)UI / cron
google-workspace-provision-userCreate or update Workspace user; upsert pf_google_workspace_user_linksHR-01 events
google-workspace-offboard-userSuspend user; queue license revoke / group removalHR-01 events
google-workspace-hr-event-subscriberRoutes HR-01 employee events to provision / offboardpgmq subscriber
google-workspace-directory-reconcileCompares HR employees vs Workspace suspended stateCron (T5.5)
google-workspace-calendar-eventCreate event with optional Meet linkPlatform API
google-workspace-license-manageIdempotent SKU assign / revokePlatform API + offboard
google-workspace-reports-ingestAudit activity → pf_audit_log (hashed actor)Cron

​
Cross-core consumption

Cores never import Google client code directly. The only allowed surface is: 
import {
  createGoogleCalendarEvent,
  assignGoogleLicense,
  revokeGoogleLicense,
} from '@/platform/integrations/google-workspace';
Gmail send routes via supabase/functions/_shared/email-provider.ts, which prefers a PF-101 connection and falls back to the legacy GMAIL_SERVICE_ACCOUNT_JSON env until each tenant migrates.

​
Open decisions (per PLAN)

DecisionMVP resolution
HR update eventsScheduled directory reconciliation (T5.5) until HR-01 ships hr_employee_updated
DWD key strategyPF-76-managed service-account key; harden toward IAM signJwt
Drive content syncMetadata-only; explicit PF-11 action for content transfer
Chat PHIAlways blocked in Chat; PF-10 templates only

​
See also