feat(connector): Google Workspace auditor (Docs, Drive, Gemini) — caminho Madruga, dor confirmada em pessoa

[FabioLeitao]

Contexto

Cross-ref: #1229 (HubSpot/CRM, mesmo caminho-Madruga). Dor real verbalizada em pessoa pelo Madruga (MTIS, design-partner em trial) na reunião de apresentação do Data Boar 1.7.4-post2 com --demo — junto com HubSpot, não depois. Corrigindo o vault, que tratava isso como "Fase 1 condicional" — na prática já é pedido confirmado.

Referência de origem pra quem for laborar (ler antes de reelaborar do zero):
p:/notes/obsidian_vault/databoar-commercial/ai-sessions/fable-opus-max-audit-2026-07-05/FOCUS_PATH_madruga_2026-07-05.md
(mesma pasta: SESSION_GUIDE_AND_SEEDS_2026-07-05.md, VERIFIED_LAYERS_2026-07-05.md como contexto adicional — mesma sessão de auditoria, mais camadas verificadas do ecossistema)

Escopo (Docs, Drive, Gemini)

• Drive: arquivos armazenados (Docs, Sheets, Slides, PDFs, uploads) — escaneáveis via Drive API, tratando cada arquivo como já é feito nos conectores de filesystem/object-storage existentes.
• Docs: conteúdo de texto de Google Docs especificamente — via Docs API (acesso mais estruturado ao corpo do documento) ou via Drive API tratando o Doc como arquivo — decisão técnica de qual abordagem, avaliar ao implementar.
• Gemini: ⚠️ precisa de esclarecimento do operador antes de implementar — não está claro se a dor do Madruga é (a) auditoria de logs de atividade/acesso do Gemini dentro do Workspace (via Admin SDK Reports API), (b) risco de conteúdo sensível vazar/parafrasear via output do Gemini, ou (c) outra coisa. Não inventar o escopo — perguntar ao operador o que exatamente o Madruga descreveu sobre o Gemini antes de codificar essa parte.

Nota de privilégio (mais delicado que HubSpot)

Auditoria de Google Workspace em nível de organização tipicamente exige domain-wide delegation (OAuth2 com escopo de admin, atuando em nome de múltiplos usuários) — é um pedido de confiança maior que o private-app-token read-only do HubSpot. Vale desenhar least-privilege com cuidado redobrado: escopo mínimo necessário, nunca mais que leitura, e documentar claramente pro Madruga (como controlador LGPD) o que exatamente está sendo concedido.

Disciplina de dado real (mesma do #1229, inegociável)

• Scan roda no ambiente do Madruga; só o manifesto (metadata) sai
• Nenhum dado real dele em repo/issue/commit/fixture
• Papéis LGPD: Madruga/MTIS = controlador; Data Boar = operador sob instrução

Tarefa — investigação antes de código

1. Perguntar ao operador o escopo exato da dor do Gemini antes de tocar nessa parte.
2. Desenhar connectors/google_workspace_connector.py seguindo o padrão de ADDING_CONNECTORS.md, cobrindo Drive + Docs primeiro (escopo mais claro).
3. Least-privilege: escopo OAuth mínimo, documentado explicitamente.
4. Fixtures sintéticas, mesmo padrão do feat(connector): HubSpot/CRM — Fase 0 do caminho Madruga (trial-to-buy) #1229 — zero dado real do Madruga.

Critério de aceite

• Esclarecimento do escopo do Gemini obtido antes de implementar essa parte
• Drive + Docs implementados seguindo o padrão de conector existente
• Least-privilege documentado explicitamente (o que é concedido, por quê)
• Fixtures sintéticas, zero dado real
• PR referencia esta issue (Closes #<N>)

[FabioLeitao]

Achado técnico (claude.ai) — reuso do padrão SharePoint, com 2 diferenças reais

Lido connectors/sharepoint_connector.py completo. O padrão de reuso é o design certo pro Google Workspace também: baixar arquivo → escrever em temp → alimentar a mesma pipeline de extração/scan já existente (_read_text_sample, scan_archive_at_path, _scan_sqlite_file_as_db) — não duplicar lógica de detecção de PII.

Duas diferenças que exigem desenho próprio, não são copy-paste do SharePoint:

1. Auth: SharePoint usa NTLM/basic simples. Auditoria de organização inteira no Google exige domain-wide delegation (service account + JSON key + escopos no Admin Console + impersonar cada usuário via subject) — bem mais complexo, precisa de desenho próprio.

2. Formatos nativos (Docs/Sheets/Slides): não baixam como arquivo bruto como o SharePoint faz (GetFileByServerRelativeUrl/$value). Precisam de chamada de export (files.export com mimeType alvo) antes de virar algo que a pipeline de extração entende. Um PDF/.docx genuíno já upado no Drive (não nativo do Google) baixaria de forma mais parecida com o SharePoint.

Vale planejar a implementação em 2 fases dentro desta issue: (a) auth + listagem via Drive API, (b) diferenciação entre arquivo genuíno (baixa direto) vs formato nativo Google (precisa export) antes de alimentar a pipeline existente.

[FabioLeitao]

Complemento (operador) — "modo auditor" pode exceder o que o SharePoint faz hoje

Ressalva importante: o sharepoint_connector.py real (lido linha a linha) só faz scan de conteúdo de arquivo — baixa, extrai texto, roda o scanner de sensibilidade. Ele não audita permissão/compartilhamento (quem tem acesso a quê, link público, compartilhamento externo, etc.).

Se "auditor" pro Google Workspace significar também isso — não só "tem PII no documento", mas "esse documento com PII está compartilhado publicamente/externamente" — isso é uma capacidade nova, sem precedente no conector existente, não só diferença de auth/export de formato nativo já apontada acima. Precisaria da API de permissões do Drive (permissions.list por arquivo) como peça adicional, não coberta pelo padrão SharePoint em nenhuma medida.

Mesma pausa de esclarecimento já vale aqui: confirmar com o operador se "modo auditor" inclui checagem de permissão/compartilhamento, ou é só scan de conteúdo (mesmo escopo do SharePoint) antes de estimar o esforço real.