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

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

> Audience: Compliance officers, security reviewers, BAA owners. Regulations in scope: HIPAA Privacy & Security Rules, HITECH breach notification, 42 CFR Part 2…

**Audience:** Compliance officers, security reviewers, BAA owners.
**Regulations in scope:** HIPAA Privacy & Security Rules, HITECH breach notification, 42 CFR Part 2 (when SUD content is sent via Workspace), state breach notification laws.

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

| Surface                              | Logged?          | What is logged                                         |
| ------------------------------------ | ---------------- | ------------------------------------------------------ |
| Gmail message bodies / subjects      | **Never**        | Only message IDs and sanitized `reason_code`           |
| Calendar event titles / descriptions | **Never**        | Only event IDs                                         |
| Chat message text                    | **Never**        | Chat is PHI-blocked entirely                           |
| Drive file contents / names          | **Never**        | Only Drive object IDs                                  |
| Reports activity actor email         | Hashed (SHA-256) | Hash + activity type only                              |
| Sync run errors                      | Sanitized        | `reason_code` enum only — no raw Google API error body |

All edge functions use the shared `createLogger` which redacts PHI tokens on emit.

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

| Review                         | Frequency | Owner             |
| ------------------------------ | --------- | ----------------- |
| Service account key rotation   | ≤ 90 days | Platform Security |
| DWD scope minimization audit   | Quarterly | Platform Security |
| BAA attestation re-affirmation | Annual    | Compliance        |
| `pf_audit_log` retention check | Annual    | Compliance        |

## 10. References

* [HIPAA Security Rule (45 CFR 164 Subpart C)](https://www.hhs.gov/hipaa/for-professionals/security/index.html)
* [Google Workspace HIPAA Implementation Guide](https://support.google.com/a/answer/3407054)
* [PF-76 Credential Vault spec](../../specs/pf/specs/PF-76-credential-vault.md)
* [PF-101 Integration Contract](../architecture/integrations/google-workspace-integration-integration.md)