Google Workspace Integration (PF-101) — Compliance & Security

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.

​

1. BAA posture

• Google Workspace BAA must be executed before any PHI-capable capability (Gmail, Calendar, Drive, Chat) is enabled.
• Attestation is recorded on pf_google_workspace_connections.baa_attested_at / baa_attested_by / baa_reference.
• All shared-client builders enforce baa_attested_at IS NOT NULL for PHI-capable capabilities — there is no opt-out flag.
• Chat is always blocked for PHI in MVP (Open Decision #4) regardless of BAA — only PF-10 approved templates may be sent via Chat.

​

2. Credential handling (PF-76 Credential Vault)

• Service account private keys, OAuth client secrets, and Pub/Sub webhook secrets are stored exclusively in the PF-76 Credential Vault.
• The connection row stores only credential_vault_ref (an opaque pointer).
• The vault enforces AES-GCM encryption with org-scoped role gating (see Credential Vault memory).
• Rotation cadence: service-account keys SHOULD be rotated at least every 90 days, or immediately on any suspected compromise. Rotation issues a new vault credential and updates the connection’s credential_vault_ref atomically.

​

3. Domain-Wide Delegation (least privilege)

• DWD scopes are mapped per capability in CAPABILITY_SCOPES (see supabase/functions/_shared/google-workspace-client.ts).
• The shared client requests only the scopes for the capability being invoked — never a union of all scopes.
• A capability whose required scopes are not authorized in Workspace Admin Console fails closed with reason_code = 'scope_missing'.
• Hardening backlog: replace static service-account keys with IAM signJwt once feasible (Open Decision #2).

​

4. PHI handling and logging

​

5. Audit trail

• pf_google_workspace_sync_runs is append-only from the application layer (RLS forbids authenticated INSERT/UPDATE/DELETE) and serves as the operational audit trail for provision / offboard / reconcile / Reports pulls.
• pf_audit_log (written by google-workspace-reports-ingest) carries Google Admin SDK audit activities for HIPAA §164.312(b) audit-controls compliance.
• Retention follows platform-wide audit retention policy.

​

6. Breach detection & response

• Reports ingestion surfaces high-risk activity types (account compromise, suspicious login, OAuth grant changes) into pf_audit_log. GR’s incident workflow can subscribe to these for breach notification triage (HITECH §13402, ARS 18-552).
• Connection health degradation publishes the pf_google_workspace_connector_degraded domain event so cross-core consumers (notifications, on-call) can react.

​

7. Data residency & exports

• The integration does not export PHI to external systems. All writes target the tenant’s own Google Workspace, governed by their BAA.
• Drive content sync is out of scope for MVP (metadata only). Any content transfer requires explicit PF-11 export action with separate consent capture.

​

8. 42 CFR Part 2 (SUD content)

• PF-101 does not enforce 42 CFR Part 2 itself — that gating happens in CL/PM consent layers before content is handed to the email or calendar provider.
• However, if a CL workflow attempts to email Part 2 content via Gmail without a valid disclosure consent, the upstream consent boundary (CL-11 / PF-44) MUST fail-closed before the call reaches the Workspace adapter.

​

9. Review cadence

​

10. References

• HIPAA Security Rule (45 CFR 164 Subpart C)
• Google Workspace HIPAA Implementation Guide
• PF-76 Credential Vault spec
• PF-101 Integration Contract