@justmpm/firebase-audit 0.1.0

package/README.md

@@ -0,0 +1,249 @@
+# @justmpm/firebase-audit
+
+> Auditor de consistência e segurança para projetos Firebase.
+> Responde: **"O sistema que você escreveu está coerente com o sistema que você pretendia construir?"**
+
+- **Pacote:** `@justmpm/firebase-audit`
+- **Comando:** `firebase-audit scan | check | verify`
+- **Skill:** `firebase-audit-skill` (junto do pacote)
+- **Modos:** biblioteca + CLI + MCP (mesmo padrão do `@justmpm/ai-tool` e `@justmpm/supergrep`)
+
+---
+
+## 1. Ideia final
+
+Cruzamos 4 fontes:
+
+```text
+CÓDIGO (queries, writes, permission calls)
+  + FIREBASE (firebase.json, firestore.rules, firestore.indexes.json)
+  + CONTRATO (firebase-audit.yaml — intenção)
+  + REALIDADE (Emulator + índices implantados)
+        ↓
+  Estas coisas estão coerentes?
+```
+
+4 motores:
+
+```text
+1. DISCOVERY  — acha tudo (usa ai-tool)
+2. ANALYZER   — monta ProjectModel de evidências + relações
+3. VERIFIER   — prova no Emulator + compara drift produção
+4. FINDINGS   — decide o que reportar (CONFIRMED / PROBABLE / NOT_OBSERVED / UNKNOWN)
+```
+
+Princípio gravado no README:
+
+> **Static analysis discovers evidence. The contract defines intent. The emulator verifies behavior. The auditor never upgrades uncertainty into certainty.**
+
+### O que reaproveitamos (não reinventar)
+
+- `@justmpm/ai-tool` (v6.1.1, já é biblioteca) → Discovery + grafo + símbolos. Usar como **dependência**:
+  ```ts
+  import { find, impact, context, map } from "@justmpm/ai-tool";
+  // find("rbac.can") → onde a função de permissão é definida + usada (pega alias)
+  // impact("src/orders/delete.ts") → quem quebra se esse arquivo mudar (CLIENT vs SERVER)
+  // context("src/orders/delete.ts") → assinaturas sem implementação
+  ```
+  Proibido chamar via terminal (`spawn npx ai-tool`) ou via MCP dentro do código. Chamada direta = tipada, rápida, testável.
+- `@justmpm/supergrep` (v0.6.0, hoje só MCP) → acha candidatos `where()`, `orderBy()`, `requirePermission()` ignorando formatação/quebra de linha. Usar como **dependência** após a Etapa 0:
+  ```ts
+  import { executeFind } from "@justmpm/supergrep";
+  // executeFind('where($FIELD, $OP, $VAL)') → candidatos
+  // depois validar cada candidato com ts-morph: importa de "firebase/firestore"?
+  ```
+  Regra: supergrep acha, ts-morph confirma. Nunca decidir só pelo texto do supergrep (ele é sintático, não resolve import nem tipo).
+- Validação final sempre no AST com ts-morph (que já vem dentro do ai-tool).
+
+### ProjectModel (núcleo)
+
+Modelo de **evidências + relações**, não só lista de entidades. Cada achado registra onde, por quê e com qual certeza. Depois os checks inferem em cima.
+
+Unidade fundamental: `OperationObservation` (não separar query de write):
+
+```text
+CLIENT → orders.delete → orders/{id} → delete → Rule X
+SERVER → orders.delete → Admin SDK → Rules bypassed (vale IAM + auth da app)
+```
+
+Schemas em Zod v4 (`z.strictObject`, `z.record(chave, valor)`, `z.json()`, `z.unknown().optional()`, sem `any`).
+
+Exemplo de `QueryShape` canônica (agente copia este formato):
+
+```ts
+// Código:
+// query(collection(db, "orders"), where("userId", "==", uid), where("status", "==", s), orderBy("createdAt", "desc"))
+{
+  scope: "COLLECTION",
+  collectionId: "orders",
+  pathTemplate: "orders",
+  filters: { equalities: ["status", "userId"], inequalities: [], arrays: [] },
+  orderBy: [{ fieldPath: "createdAt", direction: "DESCENDING" }],
+  dynamic: false,
+  confidence: "CONFIRMED",
+}
+// Regras: igualdades ordenadas no fingerprint (where a + where b == where b + where a).
+// orderBy preserva ordem. collectionGroup tem scope próprio (índice diferente).
+// Valor dinâmico (user.status) não quebra shape; campo dinâmico (where(fieldVar)) → UNKNOWN.
+```
+
+Exemplo de `Finding` (agente copia este formato):
+
+```ts
+{
+  rule: "FBA004",
+  severity: "ERROR",
+  confidence: "CONFIRMED",
+  file: "src/orders/delete.ts",
+  line: 42,
+  message: 'Permission "orders.delete" usada mas não declarada no contrato.',
+  fingerprint: "FBA004:src/orders/delete.ts:orders.delete",
+  evidence: [{ kind: "permission-call", summary: 'rbac.can("orders.delete")', confidence: "CONFIRMED" }],
+  fix: 'Declarar "orders.delete" em firebase-audit.yaml ou corrigir o nome da chamada.',
+}
+```
+
+### Contrato YAML (intenção)
+
+Agente sugere, humano aprova, auditor cobra. Agente nunca muda contrato para esconder finding.
+
+```yaml
+authorization:
+  adapter:
+    function: "rbac.can"
+  roles:
+    admin:
+      permissions: [users.read, users.write, orders.read, orders.delete]
+    user:
+      permissions: [users.read, orders.read, orders.create]
+  permissions:
+    orders.delete:
+      resource: orders
+      operation: delete
+  claims:
+    enabled: true
+    roleKey: role
+    samples:
+      admin: { role: admin }
+      user: { role: user }
+```
+
+Detalhe: limite de 1000 bytes é do **payload do crachá** (custom claim), não do mapa role→permissions. Validar tamanho com `TextEncoder` + lista de chaves reservadas OIDC/Firebase em arquivo versionado separado.
+
+Adapters configuráveis desde o dia 1 (`requirePermission`, `rbac.can`, `authorize`, etc.). Sem adapter resolvido → `UNKNOWN`, nunca adivinhar.
+
+### Skill para agentes
+
+```text
+firebase-audit-skill/
+├── SKILL.md  (sequência: descobrir → ver YAML → ver adapter → scan → ler findings → corrigir → re-scan)
+├── references/ (authorization, adapters, emulator, claims, indexes)
+├── examples/ (basic.yaml, rbac.yaml)
+└── templates/ (firebase-audit.yaml)
+```
+
+Trava principal: `The contract is an assertion of intent. Do not modify the assertion to make implementation violations disappear.`
+
+### Emulador 100% headless (sem navegador)
+
+```bash
+firebase emulators:exec --only firestore "npm test"
+curl http://localhost:8080/emulator/v1/projects/demo:ruleCoverage -o coverage.json
+```
+
+Matriz `anon / user / admin x read / create / update / delete` com `@firebase/rules-unit-testing` (`unauthenticatedContext`, `authenticatedContext`). Reaproveita `firebase.json` e porta do projeto. Requer Java. Falha build se regra ficar sem cobertura.
+
+Limites assumidos: Emulator não prova índice (produção exige, ele deixa passar). Admin SDK ignora Rules. Rules não são filtros.
+
+### Níveis de certeza (obrigatório)
+
+- `CONFIRMED` — evidência forte ou teste reprovou no Emulator
+- `PROBABLE` — estático sugere, mas há dinâmico no caminho (ex: índice)
+- `NOT_OBSERVED` — não achou uso (nunca dizer "inútil" / "sem uso")
+- `UNKNOWN` — impossível resolver estaticamente (ex: `where(fieldVar, ...)`)
+- `CONFLICTING` — interno, duas evidências se contradizem (ex: typo `order.delete` vs `orders.delete`)
+
+### 10 checks do V1
+
+| # | Check | Sev | Conf |
+|---|-------|-----|------|
+| FBA001 | `allow write/create/update/delete: if true` | ERROR | CONFIRMED |
+| FBA002 | `allow read: if true` (pode ser público proposital) | WARNING | CONFIRMED |
+| FBA003 | Admin SDK dentro de boundary Client | ERROR | PROBABLE |
+| FBA004 | Permission usada e não declarada | ERROR | CONFIRMED |
+| FBA005 | Claim nas Rules não declarada no contrato (pega typo `admn`) | WARNING | PROBABLE |
+| FBA006 | Query provavelmente exige composto não encontrado | WARNING | PROBABLE |
+| FBA007 | Índice local sem query observada | INFO | NOT_OBSERVED |
+| FBA008 | Rule sem operação observada | INFO | NOT_OBSERVED |
+| FBA009 | Adapter não resolvido | WARNING | UNKNOWN |
+| FBA010 | Query shape dinâmica | INFO | UNKNOWN |
+
+Detalhes que quebram se deixar pra depois: `write` = create+update+delete (guardar origem), `OR` nas Rules (`isAdmin() || public==true`), `resource` vs `request.resource`, `collectionGroup` com escopo próprio, `databaseId` nomeado desde o dia 1.
+
+### Decisões (porquês — não reverter sem discutir)
+
+1. **Static-first, Verifier como interface.** V1 entrega valor sem Emulator. Verifier entra depois sem reescrever o núcleo.
+2. **Índice faltando é sempre PROBABLE no V1.** Emulator deixa passar query sem índice, produção barra. Afirmar CONFIRMED seria mentir.
+3. **Sem adapter → UNKNOWN, nunca adivinhar.** Cada projeto autoriza de um jeito (`requirePermission`, `rbac.can`, `if role===`). Chutar gera falso positivo.
+4. **Contrato YAML depois do scan, não antes.** Exigir ficha antes de mostrar valor mata adoção e cria drift. V1 infere, V2 cobra contrato no `--strict`.
+5. **Evidência antes de veredito.** Analyzer registra pista com local + certeza; check decide depois. Por isso `NOT_OBSERVED` nunca vira "inútil" e `UNKNOWN` nunca vira `CONFIRMED` sem teste real.
+6. **"Leitura pública" é WARNING, não ERROR.** Pode ser blog/página pública proposital. Confirmamos o acesso aberto, não a vulnerabilidade.
+
+---
+
+## 2. Escopo
+
+**V1 — scan estático:** Discovery + 10 checks + `firebase-audit scan [--json|--strict]`. Zero-config, valor imediato.
+**V2 — check com contrato:** YAML + `Code ↔ Contract ↔ Rules` (mismatch muito amplo, role sem permissão, etc.).
+**V3 — verify:** gera cenários → roda no Emulator → tabela ALLOW/DENY + coverage.
+**V4 — drift:** local vs implantado (`LOCAL_ONLY / REMOTE_ONLY / MATCHED`).
+
+Fora do V1: Storage, Realtime DB, Hosting, App Check, Functions complexas, IAM, Data Connect.
+
+---
+
+## 3. Plano de ação
+
+### Etapa 0 — Adaptar o supergrep (pré-requisito)
+
+Hoje o supergrep só exporta `startMcpServer`. O `find` core está preso em `src/tools/find.ts`.
+
+1. Exportar `executeFind(pattern, options)` e `getTree()` em `src/index.ts` do supergrep.
+2. Publicar `@justmpm/supergrep` minor nova.
+3. No firebase-audit, declarar `"@justmpm/supergrep": "^x.y.z"` e importar direto (sem spawn, sem MCP).
+4. Fallback: se a etapa travar, usar `@ast-grep/napi` direto no firebase-audit temporariamente.
+
+### Etapa 1 — Esqueleto
+
+- `mcps-ai/firebase-audit/` com `package.json` (`@justmpm/firebase-audit`, bin `firebase-audit`, deps: `@justmpm/ai-tool`, `@justmpm/supergrep`, `zod`, `firebase-admin` só dev).
+- Schemas Zod v4: `ProjectModel`, `Finding` (com `fingerprint` + `metadata`), `AuditYaml`.
+- CLI `scan --json --strict` + saída terminal/JSON.
+- Fixtures de projeto pequeno real.
+
+### Etapa 2 — Discovery (via ai-tool)
+
+- Achar `firebase.json`, `firestore.rules`, `firestore.indexes.json`, `src/**`, `functions/**`.
+- Classificar `CLIENT / SERVER / UNKNOWN` usando grafo do ai-tool (cuidado com `src/app/api/*` que é servidor).
+
+### Etapa 3 — Extractors
+
+- Rules: só estrutura + referências + locations (sem avaliar).
+- Auth: `requirePermission("x")` / adapter configurado, seguindo referências de símbolo (pega alias).
+- Query: `where/orderBy/collection/collectionGroup` → `QueryShape` canônica (igualdades ordenadas por fingerprint, `orderBy` preserva ordem) + estados `LITERAL / RESOLVED / SYMBOLIC / UNKNOWN`.
+
+### Etapa 4 — 10 checks + CLI
+
+- Implementar FBA001–FBA010 com `fingerprint` estável pra CI (`FBA001:firestore.rules:orders:write`).
+- Regressão com fixtures.
+
+### Etapa 5 — V2 contrato + V3 emulator + V4 drift
+
+- Na ordem, sem pular. Emulator dividido em `TestCase → Scenario → Runner` (cenário completo com `resource.data.ownerId` só na V3).
+
+---
+
+## 4. Fontes validadas
+
+- Firebase Firestore Docs: Emulator não rastreia compostos, coverage em `:ruleCoverage`, Admin bypassa Rules, indices via `firestore.indexes.json` / gcloud / REST.
+- Firebase Auth Docs: `setCustomUserClaims` + `request.auth.token.*`, 1000 bytes, chaves reservadas, claims só pra acesso.
+- Zod V4 Docs: `z.strictObject`, `z.record(key, value)` com 2 args, `z.json()`, `z.unknown().optional()`.