@justmpm/firebase-audit 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   scan
-} from "./chunk-VKCDUCYE.js";
+} from "./chunk-PIRAC3KT.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -14,15 +14,41 @@ async function main() {
     console.log(pkg.version);
     return;
   }
-  if (cmd !== "scan") {
+  if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+    console.log(`firebase-audit v${pkg.version}
+
+Uso:
+  firebase-audit scan [--json] [--strict] [--adapter=fn] [--cwd=path]
+  firebase-audit check [--json] [--adapter=fn] [--cwd=path]   (alias de scan --strict)
+
+Exit codes: 0 ok (ou WARNING/INFO fora do strict); 2 quando --strict encontra ERROR.`);
+    return;
+  }
+  if (cmd !== "scan" && cmd !== "check") {
     console.error(`Comando desconhecido: ${cmd}
 Uso: firebase-audit scan [--json] [--strict] [--adapter=fn] [--cwd=path]`);
     process.exit(1);
   }
+  const strict = args.includes("--strict") || cmd === "check";
   const asJson = args.includes("--json");
-  const strict = args.includes("--strict");
-  const adapterArg = args.find((a) => a.startsWith("--adapter="))?.split("=")[1];
-  const cwdArg = args.find((a) => a.startsWith("--cwd="))?.split("=")[1];
+  const getArg = (name) => {
+    const pref = `--${name}=`;
+    const hit = args.find((a) => a.startsWith(pref));
+    if (hit) return hit.slice(pref.length);
+    const idx = args.findIndex((a) => a === `--${name}`);
+    if (idx !== -1 && args[idx + 1] && !args[idx + 1].startsWith("--")) return args[idx + 1];
+    return void 0;
+  };
+  const knownFlags = /* @__PURE__ */ new Set(["--json", "--strict", "--help", "-h", "help", "--version", "-v"]);
+  for (const a of args.slice(1)) {
+    if (a.startsWith("--") && !a.startsWith("--adapter=") && !a.startsWith("--cwd=") && a !== "--adapter" && a !== "--cwd" && !knownFlags.has(a)) {
+      console.error(`Flag desconhecida: ${a}
+Uso: firebase-audit scan [--json] [--strict] [--adapter=fn] [--cwd=path]`);
+      process.exit(1);
+    }
+  }
+  const adapterArg = getArg("adapter");
+  const cwdArg = getArg("cwd");
   const rootDir = cwdArg ?? process.cwd();
   const { findings, summary } = await scan(rootDir, { strict, adapterFn: adapterArg });
   if (asJson) {
@@ -34,7 +60,9 @@ Uso: firebase-audit scan [--json] [--strict] [--adapter=fn] [--cwd=path]`);
 FIREBASE AUDIT v${pkg.version}`);
   console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
   if (findings.length === 0) {
-    console.log("\n\u2713 Nenhum problema encontrado (V1 static-first, 10 checks).\n");
+    console.log(`
+\u2713 Nenhum problema nos checks V1+V2 implementados (parcial: FBA001-FBA004, FBA009-FBA013).
+`);
     return;
   }
   for (const f of findings) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as z from 'zod';
-import z__default from 'zod';
+import { z as z$1 } from 'zod';
 
 /**
  * firebase-audit — schemas centrais (Zod v4).
@@ -19,6 +19,7 @@ declare const ConfidenceSchema: z.ZodEnum<{
     PROBABLE: "PROBABLE";
     NOT_OBSERVED: "NOT_OBSERVED";
     UNKNOWN: "UNKNOWN";
+    CONFLICTING: "CONFLICTING";
 }>;
 declare const OperationSchema: z.ZodEnum<{
     read: "read";
@@ -69,6 +70,7 @@ declare const EvidenceSchema: z.ZodObject<{
         PROBABLE: "PROBABLE";
         NOT_OBSERVED: "NOT_OBSERVED";
         UNKNOWN: "UNKNOWN";
+        CONFLICTING: "CONFLICTING";
     }>;
     value: z.ZodOptional<z.ZodUnknown>;
     fingerprint: z.ZodOptional<z.ZodString>;
@@ -170,6 +172,7 @@ declare const QueryShapeSchema: z.ZodObject<{
         PROBABLE: "PROBABLE";
         NOT_OBSERVED: "NOT_OBSERVED";
         UNKNOWN: "UNKNOWN";
+        CONFLICTING: "CONFLICTING";
     }>;
     location: z.ZodObject<{
         file: z.ZodString;
@@ -222,6 +225,7 @@ declare const RuleSchema: z.ZodObject<{
         PROBABLE: "PROBABLE";
         NOT_OBSERVED: "NOT_OBSERVED";
         UNKNOWN: "UNKNOWN";
+        CONFLICTING: "CONFLICTING";
     }>;
     location: z.ZodObject<{
         file: z.ZodString;
@@ -288,6 +292,7 @@ declare const GraphEdgeSchema: z.ZodObject<{
         PROBABLE: "PROBABLE";
         NOT_OBSERVED: "NOT_OBSERVED";
         UNKNOWN: "UNKNOWN";
+        CONFLICTING: "CONFLICTING";
     }>;
     evidenceIds: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
@@ -378,6 +383,7 @@ declare const ProjectModelSchema: z.ZodObject<{
             PROBABLE: "PROBABLE";
             NOT_OBSERVED: "NOT_OBSERVED";
             UNKNOWN: "UNKNOWN";
+            CONFLICTING: "CONFLICTING";
         }>;
         location: z.ZodObject<{
             file: z.ZodString;
@@ -413,6 +419,7 @@ declare const ProjectModelSchema: z.ZodObject<{
             PROBABLE: "PROBABLE";
             NOT_OBSERVED: "NOT_OBSERVED";
             UNKNOWN: "UNKNOWN";
+            CONFLICTING: "CONFLICTING";
         }>;
         location: z.ZodObject<{
             file: z.ZodString;
@@ -473,6 +480,7 @@ declare const ProjectModelSchema: z.ZodObject<{
             PROBABLE: "PROBABLE";
             NOT_OBSERVED: "NOT_OBSERVED";
             UNKNOWN: "UNKNOWN";
+            CONFLICTING: "CONFLICTING";
         }>;
         value: z.ZodOptional<z.ZodUnknown>;
         fingerprint: z.ZodOptional<z.ZodString>;
@@ -494,6 +502,7 @@ declare const ProjectModelSchema: z.ZodObject<{
             PROBABLE: "PROBABLE";
             NOT_OBSERVED: "NOT_OBSERVED";
             UNKNOWN: "UNKNOWN";
+            CONFLICTING: "CONFLICTING";
         }>;
         evidenceIds: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>;
@@ -510,6 +519,7 @@ declare const FindingSchema: z.ZodObject<{
         PROBABLE: "PROBABLE";
         NOT_OBSERVED: "NOT_OBSERVED";
         UNKNOWN: "UNKNOWN";
+        CONFLICTING: "CONFLICTING";
     }>;
     file: z.ZodOptional<z.ZodString>;
     line: z.ZodOptional<z.ZodNumber>;
@@ -534,6 +544,7 @@ declare const FindingSchema: z.ZodObject<{
             PROBABLE: "PROBABLE";
             NOT_OBSERVED: "NOT_OBSERVED";
             UNKNOWN: "UNKNOWN";
+            CONFLICTING: "CONFLICTING";
         }>;
         value: z.ZodOptional<z.ZodUnknown>;
         fingerprint: z.ZodOptional<z.ZodString>;
@@ -597,12 +608,15 @@ interface DiscoveryResult {
     firestoreIndexesFile: string | null;
     auditYamlFile: string | null;
     projectId: string | null;
+    /** V2: databaseId nomeado (sempre null na V1). */
     databaseId: string | null;
+    /** V2: preenchido via varredura + ai-tool (sempre [] na V1). */
     clientFiles: string[];
+    /** V2: preenchido via varredura + ai-tool (sempre [] na V1). */
     serverFiles: string[];
 }
 declare function discover(rootDir: string): DiscoveryResult;
-/** Heurística simples CLIENT vs SERVER por caminho + import admin. */
+/** Heurística CLIENT vs SERVER: caminho manda primeiro (grafo/voz do ai-tool na V2). */
 declare function classifyOrigin(file: string, content: string): "CLIENT" | "SERVER" | "UNKNOWN";
 declare function emptyModel(rootDir: string, d: DiscoveryResult): ProjectModel;
 
@@ -611,19 +625,32 @@ declare function emptyModel(rootDir: string, d: DiscoveryResult): ProjectModel;
  * Parser leve e intencionalmente incompleto: avaliação real é do Emulator (V3).
  */
 
-type Rule = z__default.infer<typeof RuleSchema>;
+type Rule = z$1.infer<typeof RuleSchema>;
+/** Remove comentários // e block preservando strings simples. */
+declare function stripRuleComments(content: string): string;
 declare function extractRules(rulesFile: string, relFile: string): Rule[];
-/** Detecta allow ... if true preservando linha para FBA001/FBA002. */
+/** Normaliza condição para detectar público: sem if, `true`, `(true)`, `|| true`, `auth == null`. */
+declare function isPublicCondition(condition: string | undefined): {
+    isPublic: boolean;
+    confidence: "CONFIRMED" | "PROBABLE";
+};
+/** Detecta allows públicos preservando linha, path e confiança para FBA001/FBA002. */
 declare function findPublicAllows(rulesFile: string): {
     line: number;
     target: string;
+    path: string;
+    confidence: "CONFIRMED" | "PROBABLE";
 }[];
 
 /**
- * Checks estáticos V1 (FBA001–FBA010, subconjunto intencional).
+ * Checks estáticos V1 (FBA001–FBA004, FBA009–FBA011, subconjunto intencional).
  * Cada check retorna Findings com fingerprint estável para CI.
+ * Nota: FBA001/FBA002 sem linha no fingerprint (estável a formatação);
+ * FBA003/FBA004/FBA010 com linha (únicos por ocorrência — duplicatas no mesmo
+ * arquivo geram findings distintos).
  */
 
+declare const IMPLEMENTED_CHECKS: readonly ["FBA001", "FBA002", "FBA003", "FBA004", "FBA009", "FBA010", "FBA011", "FBA012", "FBA013"];
 declare function runChecks(model: ProjectModel, rootDir: string, opts?: {
     adapterFn?: string;
 }): Promise<Finding[]>;
@@ -654,4 +681,4 @@ declare function scan(rootDir: string, opts?: ScanOptions): Promise<ScanResult>;
 
 declare const VERSION: string;
 
-export { AccessOriginSchema, type AuditYaml, AuditYamlSchema, ConfidenceSchema, type DiscoveryResult, DynamicValueSchema, type Evidence, EvidenceSchema, type Finding, FindingSchema, FirestoreIndexSchema, GraphEdgeSchema, IndexFieldSchema, LocationSchema, OperationSchema, PermissionSchema, PositionSchema, type ProjectModel, ProjectModelSchema, QueryFilterSchema, QueryOrderSchema, type QueryShape, QueryShapeSchema, RoleSchema, RuleSchema, SeveritySchema, VERSION, classifyOrigin, discover, emptyModel, extractRules, findPublicAllows, runChecks, scan };
+export { AccessOriginSchema, type AuditYaml, AuditYamlSchema, ConfidenceSchema, type DiscoveryResult, DynamicValueSchema, type Evidence, EvidenceSchema, type Finding, FindingSchema, FirestoreIndexSchema, GraphEdgeSchema, IMPLEMENTED_CHECKS, IndexFieldSchema, LocationSchema, OperationSchema, PermissionSchema, PositionSchema, type ProjectModel, ProjectModelSchema, QueryFilterSchema, QueryOrderSchema, type QueryShape, QueryShapeSchema, RoleSchema, RuleSchema, type ScanOptions, type ScanResult, SeveritySchema, VERSION, classifyOrigin, discover, emptyModel, extractRules, findPublicAllows, isPublicCondition, runChecks, scan, stripRuleComments };

package/dist/index.js

@@ -7,6 +7,7 @@ import {
   FindingSchema,
   FirestoreIndexSchema,
   GraphEdgeSchema,
+  IMPLEMENTED_CHECKS,
   IndexFieldSchema,
   LocationSchema,
   OperationSchema,
@@ -24,9 +25,11 @@ import {
   emptyModel,
   extractRules,
   findPublicAllows,
+  isPublicCondition,
   runChecks,
-  scan
-} from "./chunk-VKCDUCYE.js";
+  scan,
+  stripRuleComments
+} from "./chunk-PIRAC3KT.js";
 
 // src/index.ts
 import { createRequire } from "module";
@@ -42,6 +45,7 @@ export {
   FindingSchema,
   FirestoreIndexSchema,
   GraphEdgeSchema,
+  IMPLEMENTED_CHECKS,
   IndexFieldSchema,
   LocationSchema,
   OperationSchema,
@@ -60,6 +64,8 @@ export {
   emptyModel,
   extractRules,
   findPublicAllows,
+  isPublicCondition,
   runChecks,
-  scan
+  scan,
+  stripRuleComments
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justmpm/firebase-audit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Auditor de consistência e segurança para projetos Firebase: código + Rules + índices + contrato vs comportamento. Static-first, nunca inventa certeza.",
   "keywords": [
     "firebase",
@@ -26,7 +26,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "templates",
+    "skill"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
@@ -39,6 +41,7 @@
     "@justmpm/ai-tool": "^6.1.1",
     "@justmpm/supergrep": "^0.7.0",
     "@modelcontextprotocol/sdk": "^1.25.3",
+    "yaml": "^2.9.1",
     "zod": "^4.1.0"
   },
   "devDependencies": {

package/skill/SKILL.md

@@ -0,0 +1,29 @@
+# firebase-audit-skill
+
+Skill para agentes usarem o `@justmpm/firebase-audit` do jeito certo.
+
+## Sequência obrigatória
+
+1. Descobrir projeto (`firebase.json`, `firestore.rules`, `firestore.indexes.json`)
+2. Verificar `firebase-audit.yaml` (se não existe, V1 roda zero-config)
+3. Inspecionar adapter de autorização (ex: `rbac.can`). Sem adapter resolvido → UNKNOWN, nunca adivinhar
+4. Executar `firebase-audit scan` (ou `--strict` com contrato)
+5. Ler findings (CONFIRMED corrige agora; PROBABLE investiga; NOT_OBSERVED/UNKNOWN não afirma)
+6. Corrigir código, nunca o contrato para esconder finding
+7. Reexecutar scan antes de declarar pronto
+
+## Travas
+
+- `The contract is an assertion of intent. Do not modify the assertion to make implementation violations disappear.`
+- Nunca transformar UNKNOWN em CONFIRMED sem teste no Emulator
+- Nunca dizer "unused" — apenas NOT_OBSERVED
+- Claims: 1000 bytes max, sem chaves OIDC reservadas, só controle de acesso
+
+## Emulador (V3)
+
+```bash
+firebase emulators:exec --only firestore "npm test"
+```
+
+Matriz `anon/user/admin x read/create/update/delete` com `@firebase/rules-unit-testing`.
+Cobertura em `:ruleCoverage` (JSON). Emulator não prova índice.

package/templates/firebase-audit.yaml

@@ -0,0 +1,39 @@
+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:
+    users.read:
+      resource: users
+      operation: read
+    users.write:
+      resource: users
+      operation: write
+    orders.delete:
+      resource: orders
+      operation: delete
+    orders.read:
+      resource: orders
+      operation: read
+    orders.create:
+      resource: orders
+      operation: create
+  claims:
+    enabled: true
+    roleKey: role
+    samples:
+      admin:
+        role: admin
+      user:
+        role: user