Skip to main content
Version: 1.0.1
Last Updated: 2026-06-11
Spec: PF-101 Google Workspace Integration
Status: In Progress (38/44 tasks; schema baselined, edge functions + settings UI shipped; Drive/Chat/consumer cutover pending)
Constitution Reference: Section 1.3 (Integration Patterns), Section 4.2 (PHI/PII Handling), Section 5.7 (RLS)

​
Overview

PF-101 defines the tenant-level Google Workspace connector for Admin SDK Directory, Gmail, Calendar/Meet, Drive, Chat, License Manager, and Reports APIs. It consolidates the existing Gmail and Calendar paths into a governed PF integration layer, while HR, CE, PF-10, PF-11, and PF-86 remain consumers.

​
Integration Points

​
Platform Layer Contract

Planned package: src/platform/integrations/google-workspace/

​
Event Contracts

HR-01 publisher status (confirmed 2026-04-28): hr_employee_created, hr_employee_assigned_to_site, and hr_employee_terminated are documented as published by HR-01 in HR-01-employee-directory-INTEGRATION.md §Events. The canonical-name registry rows for hr_employee_created and hr_employee_assigned_to_site are added to EVENT_CONTRACTS.md §HR Core Events alongside the existing hr_employee_terminated row. PF-76 disambiguation: “PF-76” in this document = PF-76 Credential Vault (specs/pf/specs/PF-76-credential-vault.md), not PF-76 React 19 Migration. Cross-core column comment: Migrations creating pf_google_workspace_user_links.employee_id MUST add COMMENT ON COLUMN ... IS 'Cross-core reference to hr_employees.id (HR core); no FK; validated at application layer.' per database-patterns.

​
Consumed: hr_employee_created

Publisher: HR-01
Subscriber: PF-101
Purpose: Provision or link a Google Workspace user when tenant policy enables account provisioning. Minimum payload:

​
Consumed: hr_employee_assigned_to_site

Publisher: HR-01
Subscriber: PF-101
Purpose: Reconcile site-based group, org unit, Drive, Calendar resource, or Chat mappings when a tenant explicitly enables site mapping sync. Minimum payload:

​
Consumed: hr_employee_terminated

Publisher: HR-01
Subscriber: PF-101
Purpose: Suspend/offboard linked Workspace user, revoke licenses, remove groups, and queue Drive transfer review. Minimum payload:

​
Published: pf_google_workspace_user_provisioned

Publisher: PF-101 Subscribers: PF-10, HR status consumers Purpose: Signal successful Workspace user provisioning without exposing secrets or PHI. Note: Subscribers requiring the email address must perform scoped lookups using google_user_id or profile_id.

​
Published: pf_google_workspace_connector_degraded

Publisher: PF-101
Subscribers: PF-10, PF-36
Purpose: Alert admins when credential, scope, quota, BAA gate, or sync health degrades.

​
Edge Function Contracts

All functions must use PF-76 credential retrieval, PF-42 rate limiting where applicable, sanitized errors, and correlation IDs. Tenant-scoping contract: Service-role edge functions (google-workspace-directory-sync, google-workspace-provision-user, google-workspace-offboard-user, google-workspace-calendar-sync, google-workspace-drive-sync, google-workspace-reports-ingest, google-workspace-chat-notify) MUST include explicit tenant-scoping filters on all queries against multi-tenant tables:
  • .eq('organization_id', organizationId) — REQUIRED on all multi-tenant table queries
  • .eq('connection_id', connectionId) — REQUIRED where applicable (connection-scoped resources)
Implementation MUST include validation steps to assert the presence of these filters in all multi-tenant table queries. Detailed API contracts (endpoint, request/response schemas, error cases, tenant-scoping requirements) are documented in API_CONTRACTS.md §PF-101.

​
Security and Compliance

  • No PHI-capable Gmail, Calendar, Drive, Chat, or Meet operation may run unless pf_google_workspace_connections.baa_attested_at is set and tenant policy enables the capability.
  • Raw Google credentials, service account keys, OAuth client secrets, refresh tokens, and Pub/Sub webhook secrets remain in PF-76 only.
  • Domain-wide delegation scopes are versioned, reviewed, and tested per capability.
  • Restricted Google OAuth scopes require verification/security-assessment status tracking before production use.
  • Chat messages, calendar titles, logs, cache keys, and telemetry must not contain PHI/PII.

​
Testing

  • Contract tests for each edge function with mocked Google API 200/401/403/429/5xx responses.
  • RLS tests for all PF-101 tables.
  • Integration tests for HR event consumption, Gmail send, Calendar free/busy/event, group sync preview, and Reports ingestion.
  • Manual setup wizard tests using non-PHI tenant data before production enablement.