Firebase Rules Parser

Common errors

• TypeError: Cannot read properties of undefined (reading 'init')

  cause Attempting to call `init` on an undefined interpreter instance, likely due to incorrect default import syntax for `createFirebaseRulesIntepreter` with CommonJS.
  fix Use `const createFirebaseRulesIntepreter = require('firebase-rules-parser').default;` for CommonJS, or preferably use ES module imports `import createFirebaseRulesIntepreter from 'firebase-rules-parser';`.

• Error: Cannot find module 'antlr4'

  cause The `antlr4` library, a peer dependency, is not installed in the project.
  fix Install `antlr4` as a direct dependency: `npm install antlr4` or `yarn add antlr4`.

• Property 'FirebaseRulesIntepreterFacade' does not exist on type 'typeof import("firebase-rules-parser")'.

  cause Attempting to reference the old class name `FirebaseRulesIntepreterFacade` after upgrading to v2.0.0 or later.
  fix Rename `FirebaseRulesIntepreterFacade` to `FirebaseRulesIntepreter` in your code.

Warnings

• breaking The `FirebaseRulesIntepreterFacade` class was renamed to `FirebaseRulesIntepreter`.
  Fix: Update all references from `FirebaseRulesIntepreterFacade` to `FirebaseRulesIntepreter`.
• gotcha The `antlr4` dependency was moved from a direct dependency to a peer dependency. Consumers of the library are now responsible for installing `antlr4` themselves.
  Fix: Ensure `antlr4` is installed in your project: `npm install antlr4` or `yarn add antlr4`.
• gotcha This library is based on reverse-engineering Firebase rules behavior. There might be subtle differences between its emulation and the actual Firebase rules engine, especially with less common functions (e.g., duration, latlong, timestamp) or newer Firebase features.
  Fix: Always cross-reference critical rule logic with actual Firebase behavior or official documentation. Report discrepancies to the library maintainers if significant.
• gotcha The project appears to be minimally maintained since its last release in 2019. It may not support newer Firebase rules features or address recent security updates to the Firebase platform itself.
  Fix: Evaluate against current Firebase security rules documentation. Consider contributing to the project or forking it if specific new features are required.

Install

• npm install firebase-rules-parser npm
• yarn add firebase-rules-parser yarn
• pnpm add firebase-rules-parser pnpm

Imports

• createFirebaseRulesIntepreter
  wrong:

  const createFirebaseRulesIntepreter = require('firebase-rules-parser').createFirebaseRulesIntepreter;

  correct:

  import createFirebaseRulesIntepreter from 'firebase-rules-parser';

  This is the default export for the interpreter factory. The CommonJS `require` pattern for default exports is often incorrect and might return `undefined` or the whole module object.
• createFirebaseRulesContext
  wrong:

  import createFirebaseRulesContext from 'firebase-rules-parser/createFirebaseRulesContext';

  correct:

  import { createFirebaseRulesContext } from 'firebase-rules-parser';

  This is a named export. Incorrectly importing it as a default export or from a deep path is a common mistake.
• FirebaseRulesIntepreter
  wrong:

  import { FirebaseRulesIntepreter } from 'firebase-rules-parser';

  correct:

  import type { FirebaseRulesIntepreter } from 'firebase-rules-parser';

  This is the type for the interpreter instance, not a runtime value. Use `import type` to avoid bundling issues and clearly indicate its type-only nature. Before v2.0.0, it was named `FirebaseRulesIntepreterFacade`.

Quickstart

Demonstrates initializing the Firebase rules parser with a rules string and then using it to check read and write access for different paths and authentication contexts.

import createFirebaseRulesIntepreter, { createFirebaseRulesContext } from 'firebase-rules-parser';

const rulesSource = `
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read: if request.auth.uid == userId;
      allow write: if request.auth.uid == userId && resource.data.name is string;
    }
    match /public/{documentId} {
      allow read: if true;
    }
  }
}
`;

// Create an instance of the interpreter
const rules = createFirebaseRulesIntepreter();
// Load your rules source string
rules.init(rulesSource);

// Create a context object for the access check
const context = createFirebaseRulesContext({
  auth: {
    uid: 'testUserId123',
    email: 'test@example.com'
  },
  resource: {
    id: 'testUserId123',
    data: {
      name: 'John Doe',
      value: 123
    }
  },
  // Define triggers for `exists()` and `get()` calls within rules
  onExistsCall: (path) => {
    return path === '/databases/DEFAULT/documents/users/testUserId123'; 
  },
  onGetCall: (path) => {
    if (path === '/databases/DEFAULT/documents/users/testUserId123') {
      return {
        uid: 'testUserId123',
        name: 'Test User'
      };
    }
    return null;
  }
});

// Check access for a specific path and operation
const hasReadAccess = rules.hasAccess('/databases/DEFAULT/documents/users/testUserId123', context);
console.log('Read access:', hasReadAccess.read); // Should be true

const hasWriteAccess = rules.hasAccess('/databases/DEFAULT/documents/users/testUserId123', context);
console.log('Write access:', hasWriteAccess.write); // Should be true

const noAccessContext = createFirebaseRulesContext({
  auth: { uid: 'anotherUser' },
  resource: { id: 'testUserId123', data: { name: 'Another Name' } }
});
const noReadAccess = rules.hasAccess('/databases/DEFAULT/documents/users/testUserId123', noAccessContext);
console.log('No read access:', noReadAccess.read); // Should be false or undefined

const publicReadAccess = rules.hasAccess('/databases/DEFAULT/documents/public/someDoc', noAccessContext);
console.log('Public read access:', publicReadAccess.read); // Should be true